Create a render

Upload a character image and a motion video in one request. The API immediately returns an asynchronous Render; poll it until it is ready.

Inputs

image: a character image file, or image_url
motion_video: a driving video file, or motion_video_url
background_mode: original (default), solid, or transparent
bg_color: an R,G,B color; only use it with solid

Complete example

import os
import time
import requests

base_url = "https://apis.viggle.ai/v1"
headers = {"Authorization": f"Bearer {os.environ['VIGGLE_API_KEY']}"}

with open("character.png", "rb") as image, open("motion.mp4", "rb") as motion:
    response = requests.post(
        f"{base_url}/renders",
        headers=headers,
        files={"image": image, "motion_video": motion},
    )
response.raise_for_status()
render = response.json()

while render["status"] not in {"ready", "failed", "cancelled"}:
    time.sleep(3)
    response = requests.get(
        f"{base_url}/renders/{render['id']}", headers=headers
    )
    response.raise_for_status()
    render = response.json()

if render["status"] != "ready":
    error = render.get("error", {})
    raise RuntimeError(f"{error.get('code')}: {error.get('message')}")

print(render["video_url"])

const baseUrl = "https://apis.viggle.ai/v1";
const form = new FormData();
form.append("image", imageFile);
form.append("motion_video", motionVideoFile);

let render = await fetch(`${baseUrl}/renders`, {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.VIGGLE_API_KEY}` },
  body: form,
}).then((response) => response.json());

while (!["ready", "failed", "cancelled"].includes(render.status)) {
  await new Promise((resolve) => setTimeout(resolve, 3000));
  render = await fetch(`${baseUrl}/renders/${render.id}`, {
    headers: { Authorization: `Bearer ${process.env.VIGGLE_API_KEY}` },
  }).then((response) => response.json());
}

if (render.status !== "ready") throw new Error(render.error?.message);
console.log(render.video_url);

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

Response

{
  "id": "render_123abc",
  "status": "queued",
  "progress": 0,
  "created_at": "2026-07-17T10:00:00Z"
}

When processing, stage may be analyzing, rendering, or finishing. A completed job has status: "ready" and includes video_url. In transparent mode it also includes alpha_url.

Async jobs and failures

Learn terminal states, polling, and result retention.

Get Started

Guides

Production

Inputs

Complete example

Response

Async jobs and failures

​Inputs

​Complete example

​Response

Async jobs and failures

Inputs

Complete example

Response