3D Generation - TokenLab

3D generation is asynchronous. POST /v1/3d/generations creates a TokenLab task; completed status responses return downloadable model assets such as model_url and, when available, format-specific URLs.

Choose The Input Type

Workflow	Required input	Optional fields	Notes
Text-to-3D	`model`, `prompt`	`format`, `quality`, `style`, `seed`	Best for generating a new asset from a description
Image-to-3D	`model`, `prompt`, `image` or `image_url`	`format`, `quality`, `style`, `seed`	Use only when the selected model supports image input

Query the model catalog before deciding which options to expose:

curl "https://api.tokenlab.sh/v1/models?recommended_for=3d" \
  -H "Authorization: Bearer sk-your-api-key"

Do not assume every 3D model supports both input types or every output format. Check the selected model contract before sending image, image_url, format, quality, style, or seed.

Create A 3D Task

curl https://api.tokenlab.sh/v1/3d/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tripo3d-v2.5",
    "prompt": "A stylized low-poly robot mascot with clean topology",
    "format": "glb",
    "quality": "standard"
  }'

For image-to-3D, use a public image_url when possible. Use inline/base64 image only when your client intentionally sends private media and your backend is prepared for larger request bodies.

Output Format Choices

glb is usually the safest default for web previews.
fbx and obj are useful for DCC pipelines when the selected model supports them.
usdz is useful for Apple AR workflows when exposed by the model.
Higher quality values can increase latency and cost. Expose them as explicit user choices, not hidden defaults.
seed is useful for reproducibility only when the model honors it.

Poll And Store Assets

Use the returned poll_url first. If your client needs a fixed route, use GET /v1/tasks/{id}.

curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer sk-your-api-key"

Completed tasks return model_url and may include glb_url, fbx_url, obj_url, or usdz_url. Download or cache the selected asset in your own product if users need repeat access, version history, or long-lived downloads.

Production Checklist

Persist task_id, poll_url, model, requested format, and your own asset record ID.
Resume polling after page refresh rather than creating a duplicate task.
Validate source image size and reachability before creating the task.
Keep generated asset URLs out of public pages unless the user has permission to access the asset.
Record billing_transaction_id when present for later reconciliation.

Common Errors

Symptom	Likely cause	Fix
Create response has no asset URL	3D generation is async	Poll until terminal status
Requested format missing	Model did not return that format	Fall back to `model_url` or choose a model that supports the format
Image-to-3D rejected	Selected model is text-only or image URL is unreachable	Check the model contract and validate the URL
Duplicate assets	Retry path recreated the task after timeout	Store task identity before retrying

API Reference

Topic	Reference
Create 3D	Create 3D
Get 3D Status	Get 3D Status
Get Task Status	Get Task Status
List Models	List Models
Billing & Pricing	Billing & Pricing

​Choose The Input Type

​Create A 3D Task

​Output Format Choices

​Poll And Store Assets

​Production Checklist

​Common Errors

​API Reference