V1 API reference - Viggle API

Base URL:

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 and `POST /v1/videos`’s frame 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_`, and `vid_`. 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 text-to-video)	`vid_`	`vid_3f2a9c1b7e0d4f6a`

video_id on the Videos endpoints accepts both render_ and vid_ prefixed IDs — a Render and an H3 text-to-video generation are both read back as the same unified video resource.

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.

{
  "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 for the full code vocabulary and how to use retryable/remediation.

Resources

Resource	Purpose
Characters	Reusable characters from images, with optional 3D vsplat extraction.
Motions	Reusable driving motions from videos or text prompts, with optional 3D glb extraction.
Renders	Asynchronous character+motion video generation — direct or draft-based.
Videos	H3 Video Generation — Viggle-optimized MiniMax H3 text-to-video, first-frame, and first-last-frame generation — and unified state for finished Renders and H3 generations.
Credits	Current account balance.

Code examples

Go, JavaScript, Python, and cURL requests for the current V1 endpoints.

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. See Generate Video (from Text) and Pricing and retention.

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 text-to-video generation	An asynchronous request with status, inputs, error details, and output. It is not a reusable input asset. Both are read back through the same Video resource.
Artifact	`video_url`, `alpha_url`, `vsplat_url`, `thumbnail_url`, `glb_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 text-to-video from a prompt, a first frame, or a first and last frame.
`GET`	`/v1/videos`	List the current principal’s videos — Renders and H3 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}`.
`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.

​Request and response conventions

​Public ID formats

​Success and error responses

​Resources

Code examples

​Resource model

​Endpoint index

​Conventions

Request and response conventions

Public ID formats

Success and error responses

Resources

Resource model

Endpoint index

Conventions