Is there a Python SDK for Image3D?

Not yet. The API is a standard REST API. Use any HTTP client like requests, httpx, fetch, or axios. A Python SDK is on the roadmap.

How do I handle long-running 3D generations?

Poll the /api/status endpoint every 2-5 seconds. Ultra quality jobs may take up to 60 seconds.

Can I use the Image3D API for batch processing?

Yes. Submit multiple generate requests and poll each task independently. Pro subscribers can run up to 5 concurrent generations.

API Documentation

Q: What image formats does Image3D accept?

JPEG, PNG, and WebP. For best results, use a clear photo with a single subject on a plain background.

Generate 3D models programmatically from images or text prompts. RESTful API with JSON responses and GLB model output.

Quick Start

Generate a 3D model from a text prompt in three API calls:

1. Submit a generation request

curl -X POST https://image3d.io/api/generate \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "text",
    "prompt": "a red sports car",
    "quality": "pro"
  }'

2. Poll for completion

curl https://image3d.io/api/status/TASK_ID

3. Download the GLB model from the returned URL

# Response includes model_url when status is "success"
{
  "status": "success",
  "progress": 100,
  "model_url": "https://..."
}

Authentication

All generation endpoints require a Firebase ID token passed as a Bearer token in the Authorization header. Obtain a token by signing in with Google or email magic link through the login page.

Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

Tokens expire after 1 hour. Use Firebase SDK's getIdToken(true) to refresh automatically.

Endpoints

POST /api/generate

Submit a 3D generation job from an image or text prompt.

Request Body (JSON)

Field	Type	Required	Description
mode	string	Yes	`"image"` or `"text"`
prompt	string	If text mode	Text description of the 3D model
image	string	If image mode	Base64-encoded image data
quality	string	No	`"fast"`, `"standard"`, `"pro"` (default), or `"ultra"`

Response

{
  "task_id": "abc123-def456",
  "status": "queued",
  "provider": "hunyuan3d-v3"
}

GET /api/status/{task_id}

Check the status of a generation job. Poll until status is "success" or "failed".

Response (in progress)

{
  "status": "processing",
  "progress": 45
}

Response (completed)

{
  "status": "success",
  "progress": 100,
  "model_url": "https://cdn.example.com/model.glb"
}

GET /api/balance

Check remaining generation credits for the authenticated user.

Response

{
  "balance": 580,
  "unit": "credits"
}

POST /api/create-checkout-session

Create a Stripe checkout session to purchase credits or a subscription.

Request Body

{
  "priceId": "price_xxxxx",
  "type": "pack",
  "pack": "starter",
  "generations": 10
}

Quality Tiers

Tier	Engine	Speed	Faces	PBR
Fast	Trellis	~10s	8K–15K	No
Standard	Trellis	~10s	15K–25K	No
Pro	Hunyuan3D v3	~30s	40K–60K	Yes
Ultra	Hunyuan3D v3	~60s	Up to 1M	Yes

Rate Limits

Rate limits are applied per authenticated user:

Free tier: 3 generations total
Credit packs: Limited by purchased credits
Pro subscription: 150 generations per month, up to 5 concurrent

Error Codes

Code	Meaning	Action
401	Unauthorized — missing or invalid token	Refresh your Firebase ID token
400	Bad request — missing required fields	Check request body format
402	Insufficient credits	Purchase more credits at /pricing/
429	Rate limited	Wait and retry with exponential backoff
500	Internal server error	Retry after a few seconds

FAQ

What 3D format does the API return?expand_more

The API returns GLB (binary glTF) files. You can convert to OBJ, STL, or PLY client-side using Three.js exporters, or use any 3D conversion library.

Is there a Python SDK?expand_more

Not yet. The API is a standard REST API — use any HTTP client (requests, httpx, fetch, axios). A Python SDK is on our roadmap.

How do I handle long-running generations?expand_more

Poll the /api/status/{task_id} endpoint every 2–5 seconds. The response includes a progress percentage (0–100). Ultra quality jobs may take up to 60 seconds.

Can I use the API for batch processing?expand_more

Yes. Submit multiple /api/generate requests and poll each task_id independently. Pro subscribers can run up to 5 concurrent generations.

What image formats are accepted?expand_more

JPEG, PNG, and WebP. Images are automatically resized. For best results, use a clear photo with a single subject on a plain background.