Compositing with Transparent Mode

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']}")

curl -X POST "https://apis.viggle.ai/api/render" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d "character_id=char_xxx" -d "scene_id=scene_xxx" \
  -d "background_mode=transparent"

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

Full Python 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

Green screen alternative

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.

Get Started

Guides

Advanced

Reference

Compositing with Transparent Mode

Workflow

Complete script

Tips

​Workflow

​Complete script

​Tips

Workflow

Complete script

Tips