Renders

A Render combines one Character source, one Motion source, and optional background settings into a video. All Render endpoints require Authorization: Bearer YOUR_API_KEY. Two generations of the create flow share POST /v1/renders: a direct multipart/form-data request, and a JSON request against a draft prepared by Prepare Render. Field-by-field detail lives on the split reference pages: Prepare, Create, Watch, Download. Reading render state has moved to the unified Video resource, which also covers MiniMax H3 text-to-video generations: List Videos and Get Video replace the retired GET /v1/renders and GET /v1/renders/{render_id}.

There is no published cancellation operation for a Render. cancelled is a status a Render can reach on its own, but a client cannot request it.

GET /v1/renders and GET /v1/renders/{render_id} no longer accept GET — both now answer 405 Method Not Allowed rather than 404, since other methods (POST /v1/renders, and /events//download on the id path) remain registered on the same paths. A router only returns 404 when a path has no method registered at all. If you previously checked for a 404 to detect that these routes were gone, accept 405 too, or just switch to List Videos / Get Video directly.

Create a Render directly

POST /v1/renders with multipart/form-data. For both Character and Motion, choose either a reusable ID or a direct input.

Pricing (1 credit =

0.01): **

0.01 per character in the render, per second** of the finished video. Only one character is supported per render today, so this is $0.01/second in practice, with no per-render minimum. The reservation made at creation time is an estimate; it’s finalized against the actual completed duration once the render finishes. See Pricing and retention.

Character input

Field	Type	Required	Description
`character_id`	string	One source	Ready full Character ID, for example `char_550e8400-e29b-41d4-a716-446655440000`.
`image`	file	One source	Character image uploaded directly.
`image_url`	string	One source	Public URL for a character image.

Motion input

Field	Type	Required	Description
`motion_id`	string	One source	Ready full Motion ID, for example `mot_550e8400-e29b-41d4-a716-446655440000`.
`motion_video`	file	One source	Driving video uploaded directly.
`motion_video_url`	string	One source	Public URL for a driving video.

Render settings

Field	Type	Required	Default	Description
`background_mode`	string	No	`original`	`original`, `solid`, `transparent`, or `inpaint` (accepted, treated as `original`).
`bg_color`	string	With `solid`	—	RGB color as `R,G,B`, for example `0,255,0`.

bg_color is rejected unless background_mode=solid. transparent returns an additional alpha_url when ready. If neither input family is supplied at all, the server falls back to a preconfigured default character/motion rather than rejecting the request; supplying a family partially is still an error. That default is configured per project/environment, not fixed globally, so don’t rely on it beyond a quick smoke test — always supply an explicit character and motion source in production traffic.

curl -X POST "https://apis.viggle.ai/v1/renders" \
  -H "Authorization: Bearer $VIGGLE_API_KEY" \
  -F "character_id=char_123abc" \
  -F "motion_id=mot_456def" \
  -F "background_mode=transparent"

{
  "id": "render_789ghi",
  "status": "queued",
  "progress": 0,
  "stage": null,
  "video_url": null,
  "alpha_url": null,
  "created_at": "2026-07-17T10:00:00+00:00",
  "completed_at": null,
  "error": null,
  "links": {
    "self": "/v1/renders/render_789ghi",
    "events": "/v1/renders/render_789ghi/events",
    "download": "/v1/renders/render_789ghi/download"
  }
}

links.self mirrors the retired GET /v1/renders/{render_id} path and no longer resolves. Use Get Video with the same id instead; links.events and links.download are unaffected.

Python example: create and poll

import os
import time
import requests

headers = {"Authorization": f"Bearer {os.environ['VIGGLE_API_KEY']}"}
with open("character.png", "rb") as image, open("dance.mp4", "rb") as motion:
    response = requests.post(
        "https://apis.viggle.ai/v1/renders",
        headers=headers,
        files={"image": image, "motion_video": motion},
        data={"background_mode": "original"},
    )
response.raise_for_status()
render = response.json()

while render["status"] in {"queued", "processing"}:
    time.sleep(3)
    response = requests.get(
        f"https://apis.viggle.ai/v1/videos/{render['id']}", headers=headers
    )
    response.raise_for_status()
    render = response.json()

if render["status"] == "ready":
    print(render["video_url"])
else:
    print(render["error"])

Create a Render from a prepared draft

POST /v1/renders/prepare returns a draft_id and any direct-upload plans required. Upload the declared media, then POST /v1/renders again with Content-Type: application/json, the draft_id, and a required Idempotency-Key header. This form answers 202, not 200. See Prepare Render for the full flow.

Get and list Renders

GET /v1/renders/{render_id} and GET /v1/renders are retired (405 Method Not Allowed). Fetching and listing render state now goes through the unified Video resource, which also covers MiniMax H3 text-to-video generations:

Get Video — GET /v1/videos/{video_id}, poll every 3–5 seconds until terminal, or use Watch Render instead.
List Videos — GET /v1/videos, cursor-paginated, supports status, cursor, and limit.

Download a Render

GET /v1/renders/{render_id}/download

curl -L "https://apis.viggle.ai/v1/renders/render_789ghi/download" \
  -H "Authorization: Bearer $VIGGLE_API_KEY" \
  -o output.mp4

The endpoint redirects to the finished video. You can also download video_url from a ready Render response directly.

Response and status rules

Endpoint	Success status	Response	Notes
`POST /v1/renders/prepare`	`200`	Draft + upload plans	JSON only.
`POST /v1/renders` (multipart)	`200`	Render object	Starts as `queued`; ignores `Idempotency-Key`.
`POST /v1/renders` (JSON)	`202`	Render object	Requires `Idempotency-Key`; idempotent by key + normalized input.
`GET /v1/renders`	`405`	—	Retired; use List Videos (`GET /v1/videos`) instead.
`GET /v1/renders/{render_id}`	`405`	—	Retired; use Get Video (`GET /v1/videos/{video_id}`) instead. A failed video still returns `200` there; inspect `status` and `error`.
`GET /v1/renders/{render_id}/events`	`200`	`text/event-stream`	Closes after a terminal event.
`GET /v1/renders/{render_id}/download`	`302`	Redirect	Available only when the Render is ready.

Render response fields

This is the shape returned by Render Video (from Character and/or Motion). Get Video and List Videos return the same fields except links, which they omit entirely.

Field	Type	Description
`id`	string	Public Render ID, for example `render_8f50b2c2c2b84ae0`. Preserve it exactly for status and download requests.
`status`	string	`queued`, `processing`, `ready`, `failed`, or `cancelled`.
`progress`	integer or null	Progress from 0 to 100 when available.
`stage`	string or null	Coarse progress hint when available.
`video_url`	string or null	Final video URL when status is `ready`.
`alpha_url`	string or null	Alpha-mask video URL for transparent output.
`created_at` / `completed_at`	ISO 8601 string or null	Render timestamps.
`error`	object or null	Present when status is `failed`.
`links`	object	`{self, events, download}`; absent on renders served by the legacy migration proxy. `self` mirrors the retired `GET /v1/renders/{render_id}` and no longer resolves — use Get Video instead.

Account

Characters

Motions

Video

Create a Render directly

Character input

Motion input

Render settings

Python example: create and poll

Create a Render from a prepared draft

Get and list Renders

Download a Render

Response and status rules

Render response fields

​Create a Render directly

​Character input

​Motion input

​Render settings

​Python example: create and poll

​Create a Render from a prepared draft

​Get and list Renders

​Download a Render

​Response and status rules

​Render response fields

Create a Render directly

Character input

Motion input

Render settings

Python example: create and poll

Create a Render from a prepared draft

Get and list Renders

Download a Render

Response and status rules

Render response fields