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. Each request deducts credits normally.

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 \
  -H "Authorization: Bearer YOUR_TOKEN"

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	`"standard"`, `"pro"` (default), or `"proplus"` (Ultra)
mesh_only	boolean	No	If `true`, generates untextured mesh at reduced cost. Use `/api/texture` to add textures later.

Response

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

GET /api/status/{task_id}

Check the status of a generation job. Requires authentication. 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/credits

Check remaining credits for the authenticated user. Returns subscription and purchased credits separately.

Response

{
  "credits": 1580,
  "subscription": 1200,
  "purchased": 380,
  "plan": "monthly",
  "resetDate": "2026-05-14T00:00:00.000Z"
}

POST /api/texture

Add PBR textures to a previously generated untextured mesh. Part of the two-step generation workflow.

Request Body

{
  "model_url": "/api/model/abc123-def456",
  "quality": "pro",
  "mode": "image"
}

Response

{
  "taskId": "tex-abc123",
  "provider": "tripo"
}

Poll /api/status/{taskId}?provider=tripo for completion.

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
Standard	Trellis	~10s	~15K	Basic
Pro	Hunyuan3D v3	~35s	300K	Full PBR
Ultra	Hunyuan3D v3	~55s	Up to 1M	Full PBR

Rate Limits

Rate limits are applied per authenticated user:

Free tier: 200 credits (Standard quality only)
Credit packs: Limited by purchased credits
Starter subscription: 2,500 credits per month
Creator subscription: 11,000 credits per month
Power subscription: 30,000 credits per month

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. Each request deducts credits normally.

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.