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, `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`, the draft form of `POST /v1/renders`, and every `/v1/scenes` request 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_`, `img_`, and `scn_`. 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`
Scene task	`scn_`	`scn_0199f0c2-6a1e-7c3d-9b2a-4f5e6d7c8b9a.living-room-01`

video_id on the Videos 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. A scn_ scene task is read back with Get Scene Task; its ID embeds your sessionId, so keep it whole.

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, 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	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`.
Scene Model	Build a 3D Gaussian-splat scene (`.spz`) from a text prompt or a 360° panorama, generate new posed views of it, and reconstruct it. $0.06 per scene from a prompt, $0.01 per other scene task.
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 at 480p/768p/1080p/2k, rising to $0.05 per generated second at 4k. See Generate Video (from Text) and Pricing and retention. The same endpoint’s character-animation mode uses a separate backend: a driving video is required; image-only requests are not supported. Image usage depends on enhance_mode and ordered target tags. It reserves 1 credit ($0.01) per second of measured driving-video duration, rounded up. See Using Viggle-Animate.

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 resource; image generations through Get Image.
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.
`POST`	`/v1/scenes/pano`	Build a 3D scene from a prompt or a 360° panorama.
`POST`	`/v1/scenes/custom-pano`	Build a 3D scene from a panorama placed at your own pose and scale.
`POST`	`/v1/scenes/generate`	Generate new views of a scene from a camera pose.
`POST`	`/v1/scenes/reconstruct`	Rebuild a scene’s `.spz` from its image batches.
`GET`	`/v1/scenes/{task_id}`	Get a scene task’s status and downloads, by `scn_` 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