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.

Direct answer

Can developers generate 3D models with the Image3D API?

Yes. The Image3D API lets authenticated developers submit image-to-3D or text-to-3D jobs, poll a task status endpoint, and receive a generated GLB model URL when the job completes. OBJ, STL, and PLY are handled as export workflows around the generated model, so teams should still preview the output and validate the file in the target viewer, engine, or slicer.

Best for

Automated product previews, user-generated 3D drafts, game asset prototypes, and internal creative tools.

Not a fit for

Guaranteed CAD reconstruction, print-ready repairs, rigging, or exact engineering tolerances without review.

Useful links

Studio, 3D viewer, image to GLB, and image to STL.

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: 30 credits (Standard quality only)
Credit packs: Limited by purchased credits
Starter Pack: 500 credits, export unlock, Standard usage
Maker Pack: 1,000 credits, export unlock, Pro access
Creator subscription: 4,500 credits per month with Pro and Ultra access
Power subscription: 10,000 credits per month with higher-volume Ultra access

API Workflow Notes

Image requests

Use image mode when the user already has a reference photo, AI image, product image, character concept, or sketch. Clear single-subject inputs usually produce more usable first-pass meshes.

Output validation

Always preview the returned GLB before exposing it to end users. For 3D printing flows, convert or export STL and inspect the result in Cura, PrusaSlicer, Bambu Studio, or another slicer.

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.