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.

Create a Render

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

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`, or `transparent`.
`bg_color`	string	With `solid`	—	RGB color as `R,G,B`, for example `0,255,0`.

For each input family, send one source. For example, use character_id with a newly uploaded motion_video, or upload both inputs for a one-time Render.

Valid source combinations

Character source	Motion source	Typical use
`image` / `image_url`	`motion_video` / `motion_video_url`	One-time Render.
`character_id`	`motion_video` / `motion_video_url`	Reuse one Character with a new Motion.
`image` / `image_url`	`motion_id`	Reuse one Motion with a new Character.
`character_id`	`motion_id`	Reuse both assets.

bg_color is rejected unless background_mode=solid. transparent returns an additional alpha_url when ready.

Example: one-time Render

curl -X POST "https://apis.viggle.ai/v1/renders" \
  -H "Authorization: Bearer $VIGGLE_API_KEY" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "background_mode=original"

Example: reuse assets with transparent output

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:00Z",
  "completed_at": null,
  "error": null
}

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/renders/{render['id']}", headers=headers
    )
    response.raise_for_status()
    render = response.json()

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

Get a Render

GET /v1/renders/{render_id}

Path parameter	Type	Required	Description
`render_id`	string	Yes	Full Render ID returned by `POST /v1/renders`, for example `render_8f50b2c2c2b84ae0`.

curl "https://apis.viggle.ai/v1/renders/render_789ghi" \
  -H "Authorization: Bearer $VIGGLE_API_KEY"

Poll every 3–5 seconds until the Render is terminal: ready, failed, or cancelled.

Ready and failed responses

{
  "id": "render_789ghi",
  "status": "ready",
  "progress": 100,
  "stage": null,
  "video_url": "https://assets.viggle.ai/results/output.mp4",
  "alpha_url": null,
  "created_at": "2026-07-17T10:00:00Z",
  "completed_at": "2026-07-17T10:01:10Z",
  "error": null
}

{
  "id": "render_789ghi",
  "status": "failed",
  "progress": null,
  "stage": null,
  "video_url": null,
  "alpha_url": null,
  "error": {
    "code": "task_failed",
    "message": "The render could not be completed.",
    "request_id": "req_123abc"
  }
}

Download a Render

GET /v1/renders/{render_id}/download

Path parameter	Type	Required	Description
`render_id`	string	Yes	Full ready Render ID, for example `render_8f50b2c2c2b84ae0`.

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.

Cancel a Render

DELETE /v1/renders/{render_id} Cancel a queued or processing Render owned by the current account. If the Render is already terminal, the response reports its current terminal status.

curl -X DELETE "https://apis.viggle.ai/v1/renders/render_8f50b2c2c2b84ae0" \
  -H "Authorization: Bearer $VIGGLE_API_KEY"

{
  "id": "render_8f50b2c2c2b84ae0",
  "status": "cancelled",
  "progress": null,
  "stage": null,
  "video_url": null,
  "alpha_url": null,
  "created_at": null,
  "completed_at": null,
  "error": null
}

Response and status rules

Endpoint	Success status	Response	Notes
`POST /v1/renders`	`200`	Render object	Starts as `queued`.
`GET /v1/renders/{render_id}`	`200`	Render object	A failed Render still returns `200`; inspect `status` and `error`.
`DELETE /v1/renders/{render_id}`	`200`	Render object	Returns `cancelled` or the Render’s existing terminal status.
`GET /v1/renders/{render_id}/download`	`302`	Redirect	Available only when the Render is ready.

Render response fields

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	`analyzing`, `rendering`, or `finishing` while processing.
`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`.

Get Started

Guides

Advanced

Reference

Create a Render

Character input

Motion input

Render settings

Valid source combinations

Example: one-time Render

Example: reuse assets with transparent output

Python example: create and poll

Get a Render

Ready and failed responses

Download a Render

Cancel a Render

Response and status rules

Render response fields

​Create a Render

​Character input

​Motion input

​Render settings

​Valid source combinations

​Example: one-time Render

​Example: reuse assets with transparent output

​Python example: create and poll

​Get a Render

​Ready and failed responses

​Download a Render

​Cancel a Render

​Response and status rules

​Render response fields

Create a Render

Character input

Motion input

Render settings

Valid source combinations

Example: one-time Render

Example: reuse assets with transparent output

Python example: create and poll

Get a Render

Ready and failed responses

Download a Render

Cancel a Render

Response and status rules

Render response fields