Media Guides
3D generation
Create downloadable 3D models from text or images
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.
Downloadable 3D model files are kept as automatic 30-day copies, and their URLs are TokenLab media-result URLs. Task records and separately saved assets follow their own lifecycle. See Data retention.
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, image_url or image; also prompt when the model lists it | format, quality, style, seed | Use only when the selected model supports image input |
operation is optional and is text-to-3d or image-to-3d. If you leave it out, TokenLab uses image-to-3d when you send image or image_url, and text-to-3d otherwise. If you send it, it must match the inputs. 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 only on a model whose details list image; some models accept image_url only.
Output formats
glbworks well for web previews.fbxandobjare useful for DCC pipelines when the selected model supports them.usdzis useful for Apple AR workflows when exposed by the model.- Higher
qualityvalues can increase wait time and cost. Show that choice to the user. seedaffects repeatability only on models that support it.
Get the finished model
Call GET /v1/tasks/{id} with the returned id or task_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_idwhen 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 |