3D generation

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

Input	Required	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

This API does not use an operation field. A model with text-to-3d accepts prompts; a model with image-to-3d accepts image input.

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 details 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": "tripo-h3.1",
    "prompt": "A stylized low-poly robot mascot with clean topology"
  }'

For image-to-3D, use an https URL when the source can be fetched from the internet. Use inline base64 image when the source must stay private and your server can accept the larger request body.

Output formats

glb works well 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 wait time and cost. Show that choice to the user.
seed affects repeatability only on models that support it.

Get the finished model

Use the returned poll_url. If your client needs a fixed URL, 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.

Keep the result available

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 details 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

Getting Started

Core Guides

Media Guides

Choose the input type

Create a 3D task

Output formats

Get the finished model

Keep the result available

Common Errors

API Reference

​Choose the input type

​Create a 3D task

​Output formats

​Get the finished model

​Keep the result available

​Common Errors

​API Reference

Choose the input type

Create a 3D task

Output formats

Get the finished model

Keep the result available

Common Errors

API Reference