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

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 with controlled API keys, prepaid credits, JSON responses, and GLB model output.

API access

Building image-to-3D into your product or workflow?

Sign in to create an API key, then buy credits before making generation calls. Image3D API access uses prepaid credits, hard credit caps, and dynamic settlement for variable-cost Standard jobs.

Create an API key Add credits Book a quick integration call

API key console

Create your own API key

Self-serve API access requires prepaid API balance first. Add at least 1,000 credits, about $10, before creating a live API key. Credits are priced at $1 = 100 credits; calls are precharged first, failed jobs are refunded, and completed jobs settle against the final generation cost. Web free-trial credits are not counted as API balance.

Sign in

API balance

Sign in

Prepaid or subscription credits available for API calls.

Credit rate

$1 = 100 credits

1 credit = $0.01 of prepaid API usage.

Minimum API start

$10

Add at least 1,000 credits before creating a self-serve API key.

Default API limits

1 active job

1 active generation at a time; 1,000 credits/day = up to $10/day and 5,000 credits/month by default.

Checking sign-in status...

API keys

Create a server-side key, set a label, and disable old keys when you rotate credentials.

Key	Caps	Status	Action
Sign in to view your API keys.

Recent API calls

Inspect task IDs, inputs, outputs, precharges, final charges, refunds, and upstream cost when available.

API billed

$0.00

Final settled API charges.

Refunded

$0.00

Unused precharge or failed jobs.

Upstream cost

$0.0000

Cost cap target: upstream cost stays under about 35% of billed credits when available.

Tasks

0

Recent submitted API tasks.

Task	Request	Input	Output	Cost	Status
Sign in to view API usage.

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 prepaid 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 prepaid 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 i3d_test_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 i3d_test_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 prepaid credits.

Authorization: Bearer i3d_test_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"`, `"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

{
  "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

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

Quality Tiers

Tier	Best use	Typical speed	Mesh detail	Materials
Standard	Fast shape preview	~10s	~15K faces	Basic materials
Pro	Detailed textured model	~35s	~300K faces	Full PBR
Ultra	Highest-detail review	~55s	Up to 1M faces	Full PBR

API Billing and Limits

API beta usage is prepaid and capped per API key. Image3D precharges enough credits to cover the requested quality, then settles the final charge when the generation completes. Free web-trial credits are intentionally 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.
Self-serve key	1 active job, 1,000 credits/day = up to $10/day, 5,000 credits/month by default.	A new key can test real calls, but runaway usage is capped.
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. Larger limits or Ultra access can still be reviewed manually.
Credit caps: each key has daily, monthly, and concurrency limits.
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.
Production usage: handled through prepaid credits or a custom API plan after a pilot.

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 API key	Check the Bearer token or X-API-Key header
400	Bad request — missing required fields	Check request body format
402	Insufficient prepaid API credits	Add prepaid credits at /pricing/ 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.