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/v1/generations/{task_id} endpoint every 2-5 seconds. Completed responses include model_url plus charged and refunded credits.

Can I use the Image3D API for batch processing?

Yes, within the concurrency and credit caps assigned to your API key. Submit multiple generation requests and poll each task independently.

API Beta Documentation | Image3D

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.

Direct answer

Can developers generate 3D models with the Image3D API?

Yes, through the Image3D API beta. Signed-in users can create an Image3D API key, add one-time or subscription credits, submit image-to-3D or text-to-3D jobs, poll task status, and receive a generated GLB model URL when the job completes. API usage is credit-capped and metered so higher-cost jobs do not run without paid allowance.

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 with an API beta key:

1. Submit a generation request

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

2. Poll for completion

curl https://image3d.io/api/v1/generations/TASK_ID \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

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

API beta endpoints require an Image3D API key passed as a Bearer token or X-API-Key header. Signed-in users can create API keys from the API key console on this page. Generation calls are allowed only when the connected Image3D account has enough paid credits.

Authorization: Bearer sk_live_YOUR_API_KEY

Do not expose API keys in browser code. Use them only from your server, backend job, or trusted integration environment.

Endpoints

POST /api/v1/generations

Submit a 3D generation job from an image or text prompt. The API precharges credits at submit time, then refunds any unused precharge when the job settles.

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"` (default) or `"pro"` for self-serve keys. Ultra API access is not self-serve.
mesh_only	boolean	No	If `true`, generates untextured mesh at reduced cost. Use `/api/texture` to add textures later.

Response

{
  "id": "abc123-def456",
  "status": "queued",
  "quality": "standard",
  "precharged_credits": 300
}

GET /api/v1/generations/{task_id}

Check the status of a generation job. Poll until status is "success" or "failed". Final responses include charged and refunded credits.

Response (in progress)

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

Response (completed)

{
  "status": "success",
  "progress": 100,
  "model_url": "/api/model/abc123-def456",
  "charged_credits": 30,
  "refunded_credits": 220
}

GET /api/v1/balance

Check the billable API balance for the account bound to the API key. This balance includes prepaid and subscription credits only; web free-trial credits are excluded.

Response

{
  "credits": 1580,
  "subscription": 1200,
  "purchased": 380,
  "requires_prepaid_credits": true,
  "api_key": {
    "id": "live_abc123",
    "enabled": true
  }
}

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",
  "status": "queued"
}

Texture workflow access is handled case by case during the beta. Start with /api/v1/generations unless we explicitly enable a two-step workflow for your key.

POST /api/create-checkout-session

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

Request Body

// One-time API start pack
{ "type": "credits", "pack": "api_20" }

// Custom whole-dollar amount, minimum $20
{ "type": "credits", "pack": "api_custom", "amount_usd": 20 }

// Or a recurring plan
{ "type": "subscription", "billing": "creator" }

Self-serve API quality tiers

Tier	Best use	Timing	Output
Standard	First-pass shape and texture draft	Variable; poll until success or failure	Generated GLB
Pro	Higher-detail textured draft	Variable; poll until success or failure	Generated GLB

API Billing and Limits

API usage consumes prepaid or subscription credits. Image3D precharges enough credits to cover the requested quality, then settles the final charge when the generation completes. When the paid balance runs out, add more credits. Free web-trial credits are excluded from API billing.

Item	Current beta rule	Why it matters
Credit rate	$1 = 100 credits; 1 credit = $0.01.	Developers can read every API charge as a dollar amount.
Paid balance	Use the prepaid or subscription wallet until it runs out, then top up.	There is no extra daily or monthly credit cap on a paid API key.
Image Standard	Precharge 300 credits, then settle dynamically. Minimum successful charge is 30 credits.	Variable upstream cost is protected, and unused precharge is refunded.
Image Pro	Precharge 150 credits and settle at the completed-job charge.	Higher-quality calls need enough prepaid balance before running.
Failed jobs	Refund the precharged credits automatically.	Developers can retry without paying for upstream failures.

API keys: self-serve after sign-in; generation calls require prepaid or subscription account credits.
Balance: paid credits are the limit. Add more when the wallet is empty.
Failed jobs: refunded automatically when the upstream generation fails.
Standard image jobs: dynamically settled because reconstruction cost can vary by image complexity and processing time.

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.

Webhooks and polling

Webhooks are not available in the self-serve beta yet. Store the returned task_id, poll GET /api/v1/generations/{task_id} every 2-5 seconds, and stop when the task reaches success or failed. Use exponential backoff after rate limits or temporary server errors.

Error Codes

Code	Meaning	Action
401	Unauthorized — missing or invalid API key	Check the Bearer token or X-API-Key header
400	Bad request — missing required fields	Check request body format
402	Insufficient paid API credits	Add one-time credits or a subscription before submitting generation calls
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/v1/generations/{task_id} endpoint every 2–5 seconds. The response includes status, progress, model_url when complete, and final charged/refunded credits after settlement.

Can I use the API for batch processing?expand_more

Yes, within the concurrency and credit caps assigned to your API key. Submit multiple /api/v1/generations requests and poll each task_id independently.

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.

API Beta

API Keys and Credits

Can developers generate 3D models with the Image3D API?

Best for

Not a fit for

Useful links

Quick Start

Authentication

Endpoints

Request Body (JSON)

Response

Response (in progress)

Response (completed)

Response

Request Body

Response

Request Body

Self-serve API quality tiers

API Billing and Limits

API Workflow Notes

Image requests

Output validation

Webhooks and polling

Error Codes

FAQ