Skip to main content
POST
/
api
/
scenes
/
import
Import Template
curl --request POST \
  --url https://apis.viggle.ai/api/scenes/import \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "template_id": "template_uuid",
  "name": "Group Dance"
}
'
{
  "id": "770e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "credits_reserved": 15,
  "segments": [
    {
      "uuid": "person_a1b2c3d4",
      "type": "human"
    }
  ]
}
Import a scene from a Viggle template. Supports two template types:
  • Multi-person templates — contain pre-tracked segments for each person in the video, enabling multi-character rendering
  • Video templates — plain video scenes with no person tracking, used for single-character rendering
The API automatically detects the template type based on the UUID.
Multi-Character ScenesMulti-person templates contain person segments with unique UUIDs. Use these UUIDs in Multi-Character Render to map different avatars to each person.Video templates have no segments — use them with Create Render Job for single-character rendering.

​
Using Segment UUIDs

For multi-person templates, the segments array contains UUIDs for each tracked person. Use these UUIDs in the character_mapping parameter when creating a multi-character render. 
{
  "scene_id": "scene_770e8400e29b41d4",
  "character_mapping": {
    "person_a1b2c3d4": "char_alice",
    "person_e5f6g7h8": "char_bob"
  }
}

​
Example

import requests

url = "https://apis.viggle.ai/api/scenes/import"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}
data = {
    "template_id": "YOUR_TEMPLATE_UUID",
}

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

if result.get("error_code"):
    print(f"Error: {result['error_code']} - {result.get('message')}")
else:
    scene = result["data"]
    print(f"Scene ID: {scene['id']}")
    print(f"Status: {scene['status']}")
    if scene.get("segments"):
        print("Person segments:")
        for segment in scene["segments"]:
            print(f"  - {segment['uuid']}")

Authorizations

​
Authorization
string
header
required

API key passed as Bearer token

Body

application/json
​
template_id
string
required

Viggle template UUID (multi-person or video template)

Example:

"template_uuid"

​
name
string

Optional display name for the scene

Example:

"Group Dance"

Response

Scene imported

​
id
string
Example:

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

​
status
string
Example:

"pending"

​
credits_reserved
number
Example:

15

​
segments
object[]