> ## 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` — for `POST /v1/renders` direct mode, `POST /v1/videos`'s frame images, and `POST /v1/images` (required there even without reference images) — or the draft-based render flow's direct-upload `PUT` URLs. Do not set a `Content-Type` header manually when using `FormData`; the client adds the required boundary. |
| JSON request | Motion template import, text-to-motion, `renders/prepare`, and the draft form of `POST /v1/renders` all use `application/json`. |
| Request tracing | Every response includes `X-Request-Id`. You may send your own value to correlate your own logs. |
| Source tracking | Send `X-Viggle-Source` to label the calling channel or integration. |
| Idempotency | `Idempotency-Key` is required by the JSON draft form of `POST /v1/renders` and ignored everywhere else. |
| IDs | Public IDs are typed by prefix: `char_`, `mot_`, `render_`, `vid_`, `anim_`, and `img_`. 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. There is no separate `avatar_`/`anim_` ID family — 3D vsplat and glb extraction are now tracked on the owning Character/Motion itself (`type`, `vsplat`, `glb`) and downloaded via `/export`, not through their own resources.

| Resource | Prefix | Example |
| - | - | - |
| Character | `char_` | `char_550e8400-e29b-41d4-a716-446655440000` |
| Motion | `mot_` | `mot_550e8400-e29b-41d4-a716-446655440000` |
| Render | `render_` | `render_8f50b2c2c2b84ae0` |
| Video (H3 generation) | `vid_` | `vid_3f2a9c1b7e0d4f6a` |
| Video (character animation) | `anim_` | `anim_7c1e4b9a2d0f6e3c` |
| Image generation | `img_` | `img_b16a190d-2d44-41a0-8056-ef68183c3b9e` |

`video_id` on the [Videos](/v1/api-reference/videos/list) endpoints accepts `render_`, `vid_`, and `anim_` prefixed IDs — a Render, an H3 generation, and a character-animation generation are all read back as the same unified video resource. An `img_` image generation is not a video; read it back with [Get Image](/v1/api-reference/images/get).

### Success and error responses

Creation endpoints return `200 OK` (or, for the draft-based render flow, `202 Accepted`) 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",
    "retryable": false,
    "request_id": "req_123abc",
    "details": {},
    "remediation": { "action": "fix_request", "retry_after_ms": null }
  }
}
```

See [Errors and recovery](/v1/production/errors) for the full `code` vocabulary and how to use `retryable`/`remediation`.

## Resources

| Resource | Purpose |
| - | - |
| [Characters](/v1/api-reference/characters) | Reusable characters from images, with optional 3D vsplat extraction. |
| [Motions](/v1/api-reference/motions) | Reusable driving motions from videos or text prompts, with optional 3D glb extraction. |
| [Renders](/v1/api-reference/renders) | Asynchronous character+motion video generation — direct or draft-based. |
| [Videos](/v1/api-reference/videos/list) | H3 Video Generation — Viggle-optimized MiniMax H3 text-to-video, first-frame, first-last-frame, and reference-video/image generation, plus character-animation generation on a separate backend — and unified state for finished Renders and every generation type. |
| [Viggle Image](/v1/api-reference/images/create) | Generate 1–6 PNG images from a text prompt with the `qwen` model, optionally guided by up to 8 reference images. **$0.01 per image** at `1K`, **$0.02** at `2K`. |
| [Credits](/v1/api-reference/credits) | Current account balance. |

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

<Note>
  **H3 Video Generation** (`POST /v1/videos`) generates a Viggle-optimized MiniMax H3 video with **native audio** on every clip. `quality=low` generates faster, for quicker iteration; `quality=high` produces higher-fidelity output — both tiers are billed at the same **$0.01 per generated second** at `480p`/`768p`/`1080p`/`2k`, rising to **$0.05 per generated second** at `4k`. See [Generate Video (from Text)](/v1/api-reference/videos/create-from-text) and [Pricing and retention](/v1/pricing#h3-video). The same endpoint's **character-animation mode** dispatches to a separate backend instead — one to four character images, or up to five with an optional driving video, billed at **$0.01 per second (1 credit/second)** of the driving video's duration, rounded up (5–16 credits), or a flat **$0.11** without a driving video. See [Using Viggle-Animate](/v1/api-reference/videos/create-from-character-animation).
</Note>

## 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. `type` selects whether a 3D extraction (`vsplat` on Characters, `glb` on Motions) also runs against the same source. |
| Operation | Render, H3 generation, character-animation generation, image generation | An asynchronous request with status, inputs, error details, and output. It is not a reusable input asset. Video operations are read back through the same [Video](/v1/api-reference/videos/list) resource; image generations through [Get Image](/v1/api-reference/images/get). |
| Artifact | `video_url`, `alpha_url`, `vsplat_url`, `thumbnail_url`, `mixamo_url`/`metahuman_url`/`metahuman_body_url`, `images[].url` | A downloadable result produced by an operation or export. Artifact URLs are short-lived and re-signed on every read. |

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/prepare` | Prepare a render and receive direct-upload plans. |
| `POST` | `/v1/renders` | Create a Render directly (multipart) or from a prepared draft (JSON). |
| `GET` | `/v1/renders/{render_id}/events` | Watch Render state over Server-Sent Events. |
| `GET` | `/v1/renders/{render_id}/download` | Download a ready Render. |
| `POST` | `/v1/videos` | Generate an H3 video from a prompt, a first frame, a first and last frame, or a reference video/image — or a character-animation video from a driving video and/or character images. |
| `GET` | `/v1/videos` | List the current principal's videos — Renders, H3 generations, and character-animation generations merged (cursor-paginated). Replaces the retired `GET /v1/renders`. |
| `GET` | `/v1/videos/{video_id}` | Get video status and output URLs, by `render_` or `vid_` ID. Replaces the retired `GET /v1/renders/{render_id}`. |
| `POST` | `/v1/images` | Generate 1–6 PNG images from a prompt, optionally with up to 8 reference images. |
| `GET` | `/v1/images/{image_id}` | Get an image generation's status and PNG download URLs, by `img_` ID. |
| `GET` | `/v1/credits` | Get the current account balance. |
| `POST` | `/v1/characters` | Create a reusable Character, optionally with a 3D vsplat. |
| `GET` | `/v1/characters` | List Characters. |
| `GET` | `/v1/characters/{character_id}` | Get one Character. |
| `DELETE` | `/v1/characters/{character_id}` | Delete one Character. |
| `GET` | `/v1/characters/{character_id}/export` | Download a Character's vsplat extraction. |
| `POST` | `/v1/motions` | Create a reusable Motion from video, or generate one from text (JSON), optionally with a 3D glb. |
| `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. |
| `GET` | `/v1/motions/{motion_id}/export` | Download a Motion's 3D animation. |

## Conventions

* Requests that upload media use `multipart/form-data`, or the draft-based flow's direct-upload `PUT` URLs.
* IDs are resource-prefixed, such as `char_...` and `render_...`.
* Characters and Motions use `queued`, `processing`, `ready`, and `failed`; Renders may also reach `cancelled` — but a client cannot request cancellation, only observe it.
* Error responses use `{ "error": { "code", "message", "retryable", "request_id", "details", "remediation" } }`. Internal worker and pipeline codes are never exposed.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.