Skip to main content
POST
/
api
/
scenes
/
preprocess
Create Scene
curl --request POST \
  --url https://apis.viggle.ai/api/scenes/preprocess \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form 'name=Dance Sequence' \
  --form video='@example-file' \
  --form video_url=https://example.com/dance.mp4 \
  --form background_mode=original \
  --form model=V4_Preview
{
  "scene_id": "660e8400-e29b-41d4-a716-446655440000",
  "job_id": "scene_660e8400e29b",
  "status": "pending",
  "enqueued_at": "2023-11-07T05:31:56Z"
}
Upload a driving video to create a reusable scene. The scene extracts motion data that can be applied to characters. Scene creation is free — credits are only consumed when you render. You can optionally pass background_mode to set the default background handling for renders using this scene.

​
Example

import requests

url = "https://apis.viggle.ai/api/scenes/preprocess"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
}
files = {
    "video": ("driving_video.mp4", open("driving_video.mp4", "rb"), "video/mp4"),
}
data = {
    "name": "My Scene",
}

response = requests.post(url, headers=headers, files=files, data=data)
result = response.json()

if result.get("error_code"):
    print(f"Error: {result['error_code']} - {result.get('message')}")
else:
    print(f"Scene ID: {result['scene_id']}")
    print(f"Status: {result['status']}")

​
Next Steps

After creating a scene, poll Get Scene every 5 seconds until the status becomes ready. Then you can use it in render jobs.
Don’t have a driving video? You can import a template from viggle.ai instead of uploading your own video. Templates include pre-made scenes ready for rendering.

Authorizations

​
Authorization
string
header
required

API key passed as Bearer token

Body

multipart/form-data
​
name
string
required

Display name for the scene

Example:

"Dance Sequence"

​
video
file

Driving video file (MP4, MOV, WebM). Use this or video_url.

​
video_url
string<uri>

URL to a driving video. Server fetches it. Use instead of video file upload.

Example:

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

​
background_mode
enum<string>
default:original

Background handling for the scene: original (keep video background, default), inpaint (AI fill), solid (single color), transparent (alpha mask)

Available options:
original,
solid,
transparent
​
model
enum<string>
default:V4_Preview

Avatar model to preprocess the scene with. The scene can only be rendered with the same model.

Available options:
V4_Preview,
V3_Preview

Response

Scene creation started

​
scene_id
string
Example:

"660e8400-e29b-41d4-a716-446655440000"

​
job_id
string
Example:

"scene_660e8400e29b"

​
status
string
Example:

"pending"

​
enqueued_at
string<date-time>