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",
  "id": "660e8400-e29b-41d4-a716-446655440000",
  "job_id": "scene_660e8400e29b",
  "name": "Dance Sequence",
  "status": "queued",
  "credits_reserved": 0,
  "duration_seconds": 123,
  "enqueued_at": "2023-11-07T05:31:56Z"
}

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.

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 and model to configure the scene at creation time.
Model binding: Each scene is locked to the model specified at creation (default V4_Preview). Attempting to render a scene with a different model returns error CS-UORC01-013 scene_model_mismatch. Create separate scenes for each model if needed.

​
Parameters

ParameterTypeDefaultDescription
videofilerequiredDriving video (MP4). Min 0.5s duration, min 64x64 resolution.
namestringrequiredDisplay name for the scene
background_modestringoriginaloriginal, solid, or transparent
modelstringV4_PreviewModel for preprocessing: V4_Preview or V3_Preview. Scene is permanently bound to this model.

​
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)
response.raise_for_status()
result = response.json()

    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"

​
id
string
Example:

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

​
job_id
string
Example:

"scene_660e8400e29b"

​
name
string
Example:

"Dance Sequence"

​
status
string
Example:

"queued"

​
credits_reserved
number
Example:

0

​
duration_seconds
number | null
​
enqueued_at
string<date-time>