Quick Start: Video Remix

Video Remix turns a character image and a motion video into one finished video in a single request. It’s the fastest path to a Viggle result. Set VIGGLE_API_KEY and run the example below as-is — it uses Viggle-hosted sample assets, so you don’t need to prepare your own character image or motion video first.

What you need

An API key from the Viggle Dashboard, exported as VIGGLE_API_KEY

The examples below reference placeholder sample asset URLs (https://assets.viggle.ai/samples/...). Swap in your own image/image_url and motion_video/motion_video_url, or Viggle’s published sample assets once available.

Complete example

#!/usr/bin/env bash
set -euo pipefail

response=$(curl -s -X POST "https://apis.viggle.ai/v1/renders" \
  -H "Authorization: Bearer $VIGGLE_API_KEY" \
  -F "image_url=https://assets.viggle.ai/samples/character.png" \
  -F "motion_video_url=https://assets.viggle.ai/samples/motion.mp4")
render_id=$(echo "$response" | jq -r '.id')

for _ in $(seq 1 120); do
  render=$(curl -s "https://apis.viggle.ai/v1/videos/$render_id" \
    -H "Authorization: Bearer $VIGGLE_API_KEY")
  status=$(echo "$render" | jq -r '.status')

  case "$status" in
    ready)
      echo "$render" | jq -r '.video_url'
      exit 0
      ;;
    failed|cancelled)
      echo "Render $status: $(echo "$render" | jq -c '.error')" >&2
      exit 1
      ;;
  esac
  sleep 5
done

echo "Timed out waiting for render $render_id" >&2
exit 1

const baseUrl = "https://apis.viggle.ai/v1";
const headers = { Authorization: `Bearer ${process.env.VIGGLE_API_KEY}` };
const TERMINAL = new Set(["ready", "failed", "cancelled"]);

async function createRender() {
  const form = new FormData();
  form.append("image_url", "https://assets.viggle.ai/samples/character.png");
  form.append("motion_video_url", "https://assets.viggle.ai/samples/motion.mp4");

  const response = await fetch(`${baseUrl}/renders`, {
    method: "POST",
    headers,
    body: form,
  });
  if (!response.ok) {
    const body = await response.json().catch(() => ({}));
    throw new Error(`HTTP ${response.status}: ${JSON.stringify(body.error ?? body)}`);
  }
  return response.json();
}

async function waitForRender(id) {
  for (let attempt = 0; attempt < 120; attempt++) {
    const response = await fetch(`${baseUrl}/videos/${id}`, { headers });
    if (!response.ok) {
      const body = await response.json().catch(() => ({}));
      throw new Error(`HTTP ${response.status}: ${JSON.stringify(body.error ?? body)}`);
    }
    const render = await response.json();
    if (TERMINAL.has(render.status)) return render;
    await new Promise((resolve) => setTimeout(resolve, 5000));
  }
  throw new Error(`Timed out waiting for render ${id}`);
}

const created = await createRender();
const render = await waitForRender(created.id);

if (render.status !== "ready") {
  throw new Error(`Render ${render.status}: ${JSON.stringify(render.error)}`);
}
console.log(render.video_url);

import os
import time
import requests

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

response = requests.post(
    f"{base_url}/renders",
    headers=headers,
    files={
        "image_url": (None, "https://assets.viggle.ai/samples/character.png"),
        "motion_video_url": (None, "https://assets.viggle.ai/samples/motion.mp4"),
    },
)
response.raise_for_status()
render = response.json()

for _ in range(120):
    if render["status"] in TERMINAL_STATES:
        break
    time.sleep(5)
    response = requests.get(f"{base_url}/videos/{render['id']}", headers=headers)
    response.raise_for_status()
    render = response.json()
else:
    raise TimeoutError(f"Timed out waiting for render {render['id']}")

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

print(render["video_url"])

Inputs

Character: image (file) or image_url, or a reusable character_id from the Character Quickstart
Motion: motion_video (file) or motion_video_url, or a reusable motion_id from the Motion Quickstart
background_mode: original (default), solid, or transparent
bg_color: an R,G,B color; only use it with solid

Response

{
  "id": "render_123abc",
  "status": "queued",
  "progress": 0,
  "created_at": "2026-07-17T10:00:00+00:00",
  "links": {
    "self": "/v1/renders/render_123abc",
    "events": "/v1/renders/render_123abc/events",
    "download": "/v1/renders/render_123abc/download"
  }
}

When processing, stage may be analyzing, rendering, or finishing. A completed job has status: "ready" and includes video_url — a signed link, valid for 1 hour and re-signed on every read; download it promptly or re-fetch Get Video for a fresh one. In transparent mode it also includes alpha_url. Instead of polling, you can watch the same lifecycle over Server-Sent Events with Watch Render. See Pricing and retention for how Video Remix is billed.

Async jobs and failures

Learn terminal states, polling, and result retention.

Get Started

Guides

Production

Quick Start: Video Remix

What you need

Complete example

Inputs

Response

Async jobs and failures

​What you need

​Complete example

​Inputs

​Response

Async jobs and failures

What you need

Complete example

Inputs

Response