> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aisonar.dev/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 AI Sonar 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:

Use the input type rather than an `operation` field for this endpoint. Model metadata reports 3D capabilities as `text-to-3d` and/or `image-to-3d`; `3d-generation` is not a public request operation.

```bash theme={null}
curl "https://api.aisonar.dev/v1/models?recommended_for=3d" \
  -H "Authorization: Bearer sk-your-api-key"
```

Current Tripo examples include `tripo-h3.1` for high-quality text/image-to-3D workflows and `tripo-p1.0` for production-style 3D asset generation. Use the Models API to confirm the selected model supports your input type and output format.

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

```bash theme={null}
curl https://api.aisonar.dev/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",
    "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.aisonar.dev/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 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](/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)                    |