Skip to main content
POST
/
api
/
render
Create Render Job
curl --request POST \
  --url https://apis.viggle.ai/api/render \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form ref_image='@example-file' \
  --form ref_image_url=https://example.com/character.png \
  --form driving_video='@example-file' \
  --form driving_video_url=https://example.com/dance.mp4 \
  --form character_id=char_550e8400e29b41d4 \
  --form scene_id=scene_660e8400e29b41d4 \
  --form 'character_mapping={"person_a1b2c3d4": "char_alice", "person_e5f6g7h8": "char_bob"}' \
  --form model=V4_Preview \
  --form background_mode=original \
  --form 'bg_color=0,255,0' \
  --form fast=false
{
  "job_id": "job_abc123xyz",
  "status": "queued",
  "mode": "full_pipeline",
  "enqueued_at": "2023-11-07T05:31:56Z",
  "poll_url": "/api/render/job_abc123xyz",
  "status_url": "/api/render/job_abc123xyz"
}

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.

Start a video render job using multipart/form-data.
Two workflows available:
  • On-Demand: Upload ref_image and driving_video directly — no preprocessing, no stored assets. Costs 1 credit/second of video.
  • Reusable Assets: Pre-create characters and scenes (both free) for reuse across renders. Each render costs 1 credit/second.
  • Fast Mode: Set fast=true for 2x rendering speed at 2x credit cost. Requires a driving_video upload or a scene_id.

​
Error Handling

If the request fails, the response includes a structured error with an error_code: 
{
  "detail": {
    "error_code": "CS-ORIV-001",
    "message": "Reference image is required",
    "action": "Upload a ref_image (PNG/JPG)"
  }
}
Common error codes for this endpoint:
CodeCauseFix
CS-ORAU-001Missing API keyAdd Authorization: Bearer sk-... header
CS-ORAU-002Invalid API keyCheck your key is correct
CS-ORIV-001Missing reference imageUpload ref_image
CS-ORIV-002Missing driving videoUpload driving_video or provide scene_id
CS-ORIV-004Video too longKeep under 5 minutes
CS-ORCR-001Insufficient creditsTop up credits
See Error Codes for the full list. When contacting [email protected], include the error_code and your job ID.

​
Examples

​
On-Demand Render (upload files directly)

import requests

url = "https://apis.viggle.ai/api/render"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

with open("character.png", "rb") as img, open("driving.mp4", "rb") as vid:
    resp = requests.post(
        url,
        headers=headers,
        files={
            "ref_image": ("character.png", img, "image/png"),
            "driving_video": ("driving.mp4", vid, "video/mp4"),
        },
        data={"background_mode": "original"},
    )

data = resp.json()
if "detail" in data:
    print(f"Error {data['detail']['error_code']}: {data['detail']['message']}")
else:
    print(f"Job created: {data['job_id']}")
    print(f"Poll: GET /api/render/{data['job_id']}")

​
Reusable Assets Render (pre-created character + scene)

import requests

url = "https://apis.viggle.ai/api/render"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

resp = requests.post(
    url,
    headers=headers,
    data={
        "character_id": "char_550e8400e29b41d4",
        "scene_id": "scene_660e8400e29b41d4",
        "background_mode": "original",
    },
)

data = resp.json()
if "detail" in data:
    print(f"Error {data['detail']['error_code']}: {data['detail']['message']}")
else:
    print(f"Job created: {data['job_id']}")

​
Next Steps

After creating a render job, poll Get Job Status every 3-5 seconds (no auth required). When status is complete, use the cdn_url field to download the final video.

Authorizations

​
Authorization
string
header
required

API key passed as Bearer token

Body

multipart/form-data
​
ref_image
file

Character reference image file (PNG, JPG). Use this or ref_image_url.

​
ref_image_url
string<uri>

URL to a character image. The server fetches it. Use instead of ref_image file upload.

Example:

"https://example.com/character.png"

​
driving_video
file

Driving video file (MP4). Use this or driving_video_url.

​
driving_video_url
string<uri>

URL to a driving video. The server fetches it. Use instead of driving_video file upload.

Example:

"https://example.com/dance.mp4"

​
character_id
string

ID of a ready character (for preprocessed renders)

Example:

"char_550e8400e29b41d4"

​
scene_id
string

ID of a ready scene (for preprocessed renders)

Example:

"scene_660e8400e29b41d4"

​
character_mapping
string

JSON string mapping segment UUIDs to character IDs (for multi-character render)

Example:

"{\"person_a1b2c3d4\": \"char_alice\", \"person_e5f6g7h8\": \"char_bob\"}"

​
model
enum<string>
default:V4_Preview

Avatar model. V3_Preview uses a different rendering model with a dedicated GPU pool. Scenes preprocessed on one model cannot be rendered on the other.

Available options:
V4_Preview,
V3_Preview
​
background_mode
enum<string>
default:original

Background handling: original (default, person removed via AI inpainting), solid (single color), transparent (alpha mask for compositing)

Available options:
original,
solid,
transparent
​
bg_color
string

RGB string for solid background color, e.g., "0,255,0". Only used when background_mode is solid.

Example:

"0,255,0"

​
fast
boolean
default:false

Enable fast mode for 2x rendering speed. Costs 2x credits. Requires a driving_video upload or a scene_id.

Response

Render job created

​
job_id
string
Example:

"job_abc123xyz"

​
status
string
Example:

"queued"

​
mode
string

The render mode (e.g. full_pipeline, preprocessed, fast)

Example:

"full_pipeline"

​
enqueued_at
string<date-time>
​
poll_url
string

URL to poll for job status

Example:

"/api/render/job_abc123xyz"

​
status_url
string

URL to get job status

Example:

"/api/render/job_abc123xyz"