> ## 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.

# V1 API reference

> Resource-oriented reference for the Viggle V1 API.

Base URL:

```text theme={null}
https://apis.viggle.ai/v1
```

All endpoints require `Authorization: Bearer YOUR_API_KEY`.

## Request and response conventions

| Item            | V1 convention                                                                                                                                           |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Base URL        | `https://apis.viggle.ai/v1`                                                                                                                             |
| Authentication  | `Authorization: Bearer YOUR_API_KEY` on every endpoint, including status and download requests.                                                         |
| Media upload    | Use `multipart/form-data`. Do not set a `Content-Type` header manually when using `FormData`; the client adds the required boundary.                    |
| JSON request    | Motion template import uses `application/json`.                                                                                                         |
| Request tracing | Every response includes `X-Request-Id`. You may send one to correlate your own logs.                                                                    |
| IDs             | Public IDs are typed by prefix: `char_`, `mot_`, `render_`, `avatar_`, and `anim_`. Never use an ID from one resource family where another is expected. |

### Public ID formats

IDs are opaque values generated by Viggle. Preserve them exactly as returned; do not construct, shorten, or strip their prefixes.

| Resource  | Prefix    | Example                                     |
| --------- | --------- | ------------------------------------------- |
| Character | `char_`   | `char_550e8400-e29b-41d4-a716-446655440000` |
| Motion    | `mot_`    | `mot_550e8400-e29b-41d4-a716-446655440000`  |
| Render    | `render_` | `render_8f50b2c2c2b84ae0`                   |
| Avatar    | `avatar_` | `avatar_8f50b2c2c2b84ae0`                   |
| Animation | `anim_`   | `anim_8f50b2c2c2b84ae0`                     |

### Success and error responses

Creation endpoints return `200 OK` with an asynchronous resource in `queued` state. A resource status request can return `200 OK` with `status: "failed"`; always inspect both the HTTP status and the response body.

```json theme={null}
{
  "error": {
    "code": "invalid_request",
    "message": "Request failed validation",
    "request_id": "req_123abc"
  }
}
```

## Resources

| Resource                                      | Purpose                                            |
| --------------------------------------------- | -------------------------------------------------- |
| [Characters](/v1/api-reference/characters)    | Reusable characters from images.                   |
| [Motions](/v1/api-reference/motions)          | Reusable driving motions from videos.              |
| [Renders](/v1/api-reference/renders)          | Asynchronous video generation.                     |
| [Credits](/v1/api-reference/credits)          | Current account balance.                           |
| [3D Conversion](/v1/api-reference/3d-outputs) | Image-to-3D and video-to-3D conversion operations. |

<Card title="Code examples" icon="code-xml" href="/v1/api-reference/code-examples">
  Go, JavaScript, Python, and cURL requests for the current V1 endpoints.
</Card>

## Resource model

V1 separates reusable content from work performed on that content:

| Layer     | Current V1 examples                   | Meaning                                                                                                   |
| --------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| Asset     | Character, Motion                     | A reusable item with a stable public ID. It can be referenced by multiple Render requests.                |
| Operation | Render, 3D Conversion                 | An asynchronous request with status, inputs, error details, and output. It is not a reusable input asset. |
| Artifact  | `video_url`, `alpha_url`, `model_url` | A downloadable result produced by an operation. Artifact URLs can expire.                                 |

Direct `image` and `motion_video` inputs on `POST /v1/renders` are one-time inputs. They do not create a Character or Motion that appears in an asset list. Create an asset explicitly when it needs to be reused.

## Endpoint index

| Method   | Endpoint                           | Description                             |
| -------- | ---------------------------------- | --------------------------------------- |
| `POST`   | `/v1/renders`                      | Create an asynchronous video Render.    |
| `GET`    | `/v1/renders/{render_id}`          | Get Render status and output URLs.      |
| `DELETE` | `/v1/renders/{render_id}`          | Cancel a Render.                        |
| `GET`    | `/v1/renders/{render_id}/download` | Download a ready Render.                |
| `GET`    | `/v1/credits`                      | Get the current account balance.        |
| `POST`   | `/v1/characters`                   | Create a reusable Character.            |
| `GET`    | `/v1/characters`                   | List Characters.                        |
| `GET`    | `/v1/characters/{character_id}`    | Get one Character.                      |
| `DELETE` | `/v1/characters/{character_id}`    | Delete one Character.                   |
| `POST`   | `/v1/motions`                      | Create a reusable Motion.               |
| `POST`   | `/v1/motions/import`               | Import a Motion from a Viggle template. |
| `GET`    | `/v1/motions`                      | List Motions.                           |
| `GET`    | `/v1/motions/{motion_id}`          | Get one Motion.                         |
| `DELETE` | `/v1/motions/{motion_id}`          | Delete one Motion.                      |
| `POST`   | `/v1/avatars`                      | Create a 3D Avatar from an image.       |
| `GET`    | `/v1/avatars/{avatar_id}`          | Get Avatar status and output URL.       |
| `POST`   | `/v1/animations`                   | Create a 3D Animation from a video.     |
| `GET`    | `/v1/animations/{animation_id}`    | Get Animation status and output URL.    |

## Conventions

* Requests that upload media use `multipart/form-data`.
* IDs are resource-prefixed, such as `char_...` and `render_...`.
* All asynchronous resources use `queued`, `processing`, `ready`, and `failed`; Renders may also be `cancelled`.
* Error responses use `{ "error": { "code", "message", "request_id" } }`. Internal worker and pipeline codes are never exposed.