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.
3D model files are not covered by the automatic 30-day HTTP(S) generated-media copy retention. Task records and any 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, 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
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
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_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 |