Render with background_mode=transparent to get a main video + mask video for compositing onto any background.
Workflow
Render with transparent mode
import requests, time
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, data={
"character_id": "char_xxx",
"scene_id": "scene_xxx",
"background_mode": "transparent",
}).json()
print(f"Job ID: {job['job_id']}")
Wait and download
Poll until complete, then download the video and mask from the CDN URLs in the status response.while True:
status = requests.get(f"{BASE}/api/render/{job['job_id']}").json()
if status["status"] == "complete":
print(f"Video: {status['cdn_url']}")
break
elif status["status"] == "failed": raise Exception(status.get("error_message"))
time.sleep(3)
# Download main video
video = requests.get(status["cdn_url"])
open("character.mp4", "wb").write(video.content)
Composite in your editor
After Effects
DaVinci Resolve
FFmpeg
- Import
character.mp4 and the mask video
- Place
character.mp4 above your background layer
- Add the mask as a Track Matte (Luma Matte)
- Character composites over your custom background
- Place background on V1,
character.mp4 on V2
- Add the mask video in Fusion as alpha input
- Use MatteControl node to apply the mask
ffmpeg -i background.mp4 -i character.mp4 -i character_mask.mp4 \
-filter_complex "[2:v]format=gray[mask];[1:v][mask]alphamerge[fg];[0:v][fg]overlay=0:0" \
-c:v libx264 -preset fast composited_output.mp4
Complete script
import requests, time
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, data={
"character_id": "char_xxx", "scene_id": "scene_xxx",
"background_mode": "transparent",
}).json()
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)
video = requests.get(status["cdn_url"])
open("character.mp4", "wb").write(video.content)
print(f"Saved character.mp4")
Tips
If your editor supports chroma keying, use background_mode=solid with bg_color=0,255,0 instead. Traditional green screen without a separate mask file.
