Skip to main content
Send a character image and driving video directly. No preprocessing, no stored assets — one API call to start rendering.

​
Prerequisites

  • A Viggle API key (get one here)
  • A reference image (PNG or JPG)
  • A driving video (MP4)

​
Workflow

Render

Upload ref_image and driving_video to start a job. 1 credit/sec of output.
import requests
API_KEY, BASE = "YOUR_API_KEY", "https://apis.viggle.ai"
headers = {"Authorization": f"Bearer {API_KEY}"}

job = requests.post(f"{BASE}/api/render", headers=headers, files={
    "ref_image": open("character.png", "rb"),
    "driving_video": open("dance.mp4", "rb"),
}).json()
print(f"Job ID: {job['job_id']}")

Poll for completion

Poll every 3-5 seconds. No auth required for the status endpoint.
import time
while True:
    status = requests.get(f"{BASE}/api/render/{job['job_id']}").json()
    if status["status"] == "complete": break
    elif status["status"] == "failed": raise Exception(status.get("error_message"))
    time.sleep(3)

Download

When the job is complete, use the cdn_url from the status response to download the video.
cdn_url = status["cdn_url"]
video = requests.get(cdn_url)
open("output.mp4", "wb").write(video.content)

​
Render options

Pass additional fields alongside ref_image and driving_video: 
job = requests.post(f"{BASE}/api/render", headers=headers, files={
    "ref_image": open("character.png", "rb"),
    "driving_video": open("dance.mp4", "rb"),
}, data={
    "background_mode": "solid",
    "bg_color": "0,255,0",
    "fast": "true",
}).json()
See Render Options for all available parameters.

​
Using V3 model

Pass model=V3_Preview to render with the V3 avatar model: 
curl -X POST "https://apis.viggle.ai/api/render" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" -F "[email protected]" \
  -F "model=V3_Preview"

​
Using URL inputs

Pass URLs instead of uploading files. The server fetches the content: 
curl -X POST "https://apis.viggle.ai/api/render" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d "ref_image_url=https://example.com/character.png" \
  -d "driving_video_url=https://example.com/dance.mp4"

​
On-Demand vs Preprocessing

On-DemandPreprocessing
SetupNone — send files directlyCreate character + scene first
SpeedIncludes preprocessing time~3x faster
ReuseNo stored assetsReuse across renders
Best forOne-off renders, prototypingProduction, repeated renders

​
What’s next?

Preprocessing Guide

Pre-create assets for 3x faster renders

Import Templates

Use pre-made templates from viggle.ai

Render Options

Background mode, fast mode, and more