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

{
  "error": {
    "code": "invalid_request",
    "message": "Request failed validation",
    "request_id": "req_123abc"
  }
}

Resources

Resource	Purpose
Characters	Reusable characters from images.
Motions	Reusable driving motions from videos.
Renders	Asynchronous video generation.
Credits	Current account balance.
3D Conversion	Image-to-3D and video-to-3D conversion operations.

Code examples

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

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.

​Request and response conventions

​Public ID formats

​Success and error responses

​Resources