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

# 3D Conversion

> Create and retrieve image-to-3D and video-to-3D conversion operations.

V1 exposes two independent 3D conversion operations: Avatar converts an image into a 3D character model, and Animation converts a video into a 3D animation. These operations return a downloadable result and are separate from reusable Character and Motion assets. All endpoints require `Authorization: Bearer YOUR_API_KEY`.

## Create an Avatar

`POST /v1/avatars`

Send `multipart/form-data`.

| Field   | Type | Required | Description                         |
| ------- | ---- | :------: | ----------------------------------- |
| `image` | file |    Yes   | Image used to create the 3D Avatar. |

```bash theme={null}
curl -X POST "https://apis.viggle.ai/v1/avatars" \
  -H "Authorization: Bearer $VIGGLE_API_KEY" \
  -F "image=@character.png"
```

```json theme={null}
{
  "id": "avatar_123abc",
  "status": "queued",
  "model_url": null,
  "created_at": null,
  "updated_at": null,
  "error": null
}
```

## Get an Avatar

`GET /v1/avatars/{avatar_id}`

| Path parameter | Type   | Required | Description                                            |
| -------------- | ------ | :------: | ------------------------------------------------------ |
| `avatar_id`    | string |    Yes   | Full Avatar ID, for example `avatar_8f50b2c2c2b84ae0`. |

```bash theme={null}
curl "https://apis.viggle.ai/v1/avatars/avatar_123abc" \
  -H "Authorization: Bearer $VIGGLE_API_KEY"
```

## Create an Animation

`POST /v1/animations`

Send `multipart/form-data`.

| Field   | Type | Required | Description                                          |
| ------- | ---- | :------: | ---------------------------------------------------- |
| `video` | file |    Yes   | Motion-source video used to create the 3D Animation. |

```bash theme={null}
curl -X POST "https://apis.viggle.ai/v1/animations" \
  -H "Authorization: Bearer $VIGGLE_API_KEY" \
  -F "video=@dance.mp4"
```

## Get an Animation

`GET /v1/animations/{animation_id}`

| Path parameter | Type   | Required | Description                                             |
| -------------- | ------ | :------: | ------------------------------------------------------- |
| `animation_id` | string |    Yes   | Full Animation ID, for example `anim_8f50b2c2c2b84ae0`. |

```bash theme={null}
curl "https://apis.viggle.ai/v1/animations/anim_456def" \
  -H "Authorization: Bearer $VIGGLE_API_KEY"
```

Poll either resource every 5 seconds until `status` is `ready` or `failed`. A ready response contains `model_url`, which is the downloadable 3D artifact.

<Warning>
  3D task records and signed output URLs are retained for one hour. Download the finished artifact promptly and persist it in your own storage if needed.
</Warning>

## 3D response fields

| Field                       | Type                    | Description                                    |
| --------------------------- | ----------------------- | ---------------------------------------------- |
| `id`                        | string                  | `avatar_...` or `anim_...` public resource ID. |
| `status`                    | string                  | `queued`, `processing`, `ready`, or `failed`.  |
| `model_url`                 | string or null          | Downloadable 3D result when ready.             |
| `created_at` / `updated_at` | ISO 8601 string or null | Task timestamps.                               |
| `error`                     | object or null          | Present when the task fails.                   |

<Note>
  V1 currently supports create and get operations for 3D resources. List and delete endpoints are not available.
</Note>

## Endpoint response rules

| Endpoint                            | Success status | Response             | Parameters                  |
| ----------------------------------- | -------------- | -------------------- | --------------------------- |
| `POST /v1/avatars`                  | `200`          | 3D Conversion object | `image` is required.        |
| `GET /v1/avatars/{avatar_id}`       | `200`          | 3D Conversion object | `avatar_id` is required.    |
| `POST /v1/animations`               | `200`          | 3D Conversion object | `video` is required.        |
| `GET /v1/animations/{animation_id}` | `200`          | 3D Conversion object | `animation_id` is required. |