Documentation Index
Fetch the complete documentation index at: https://docs.viggle.ai/llms.txt
Use this file to discover all available pages before exploring further.
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()
Using V3 model
Pass model=V3_Preview to render with the V3 avatar model:
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-Demand | Preprocessing |
|---|
| Setup | None — send files directly | Create character + scene first |
| Speed | Includes preprocessing time | ~3x faster |
| Reuse | No stored assets | Reuse across renders |
| Best for | One-off renders, prototyping | Production, 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
