> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# 3D Generation

> Create text-to-3D or image-to-3D tasks, poll for completed assets, and handle downloadable model files.

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:

```bash theme={null}
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

```bash theme={null}
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}`.

```bash theme={null}
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](/api-reference/3d/create-3d)                |
| Get 3D Status     | [Get 3D Status](/api-reference/3d/get-3d-status)        |
| Get Task Status   | [Get Task Status](/api-reference/tasks/get-task-status) |
| List Models       | [List Models](/api-reference/models/list-models)        |
| Billing & Pricing | [Billing & Pricing](/guides/billing)                    |