> ## 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.

# Import Template

> Import a scene from a Viggle template

Bring a scene into your account straight from a Viggle template. There are two kinds:

* **Multi-person templates** — come with tracked person UUIDs for each person in the video
* **Video templates** — plain video scenes, no person tracking

You don't need to tell us which is which — we figure out the type automatically from the UUID.

<Tip>
  You can browse and copy template UUIDs over at [viggle.ai](https://viggle.ai) — the [Import Templates guide](/guides/import-templates) walks you through it. Importing is free; you only pay credits when you render.
</Tip>

## Parameters

Send as JSON (`Content-Type: application/json`).

| Parameter       | Type   | Required | Description                                                |
| --------------- | ------ | :------: | ---------------------------------------------------------- |
| `template_uuid` | string |     ✅    | The Viggle template UUID (multi-person or video template). |
| `name`          | string |          | Optional display name for the imported scene.              |

## Response

```json theme={null}
{
  "scene_id": "770e8400-e29b-41d4-a716-446655440000",
  "job_id": "scene_770e8400e29b",
  "status": "pending",
  "message": "Scene import initiated. Check status for updates.",
  "character_uuids": ["person_a1b2c3d4", "person_e5f6g7h8"]
}
```

| Field             | Description                                                                                        |
| ----------------- | -------------------------------------------------------------------------------------------------- |
| `scene_id`        | Scene UUID. Poll [Get Scene](/api-reference/scenes/get) with it until `status` is `ready`.         |
| `status`          | Starts at `pending`; the import runs in the background.                                            |
| `character_uuids` | Tracked person UUIDs, for **multi-person** templates only. Empty/absent for plain video templates. |

## Example

<CodeGroup>
  ```python Python theme={null}
  import requests

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

  response = requests.post(url, headers=headers, json=data)
  response.raise_for_status()
  result = response.json()
  print(f"Scene ID: {result['scene_id']}")
  print(f"Status: {result['status']}")
  if result.get("character_uuids"):
      print("Tracked persons:")
      for uuid in result["character_uuids"]:
          print(f"  - {uuid}")
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://apis.viggle.ai/api/scenes/import", {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      template_uuid: "YOUR_TEMPLATE_UUID",
    }),
  });

  const result = await response.json();

  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  console.log(`Scene ID: ${result.scene_id}`);
  console.log(`Status: ${result.status}`);
  if (result.character_uuids) {
    console.log("Tracked persons:");
    result.character_uuids.forEach((uuid) => console.log(`  - ${uuid}`));
  }
  ```

  ```bash cURL theme={null}
  curl -X POST https://apis.viggle.ai/api/scenes/import \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"template_uuid": "YOUR_TEMPLATE_UUID"}'
  ```
</CodeGroup>


## OpenAPI

````yaml POST /api/scenes/import
openapi: 3.0.3
info:
  title: Viggle API
  description: Generate AI-powered character animation videos
  version: 2.0.0
  contact:
    name: Viggle Support
    url: https://viggle.ai
servers:
  - url: https://apis.viggle.ai
    description: Production server
security: []
paths:
  /api/scenes/import:
    post:
      tags:
        - Scenes
      summary: Import Template
      description: >-
        Import a scene from a Viggle template. Supports multi-person templates
        (with tracked person UUIDs) and video templates (plain video for
        single-character rendering).
      operationId: importScene
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - template_uuid
              properties:
                template_uuid:
                  type: string
                  description: Viggle template UUID (multi-person or video template)
                  example: template_uuid
                name:
                  type: string
                  description: Optional display name for the scene
                  example: Group Dance
      responses:
        '200':
          description: Scene imported
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SceneImported'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Template not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorStructured'
              example:
                detail:
                  error_code: CS-UORC01-003
                  message: Template not found. Double-check the template_uuid.
      security:
        - bearerAuth: []
components:
  schemas:
    SceneImported:
      type: object
      properties:
        scene_id:
          type: string
          example: 770e8400-e29b-41d4-a716-446655440000
          description: Scene UUID
        job_id:
          type: string
          example: scene_770e8400e29b
        status:
          type: string
          example: pending
        message:
          type: string
          example: Scene import initiated. Check status for updates.
        character_uuids:
          type: array
          description: UUIDs of tracked persons in the template.
          items:
            type: string
          example:
            - person_a1b2c3d4
            - person_e5f6g7h8
    ErrorStructured:
      type: object
      description: >-
        Structured error. `detail` carries a machine-readable `error_code` plus
        a human-readable `message`.
      properties:
        detail:
          type: object
          properties:
            error_code:
              type: string
              example: CS-UORC01-008
            message:
              type: string
              example: Insufficient credits. Top up your balance to continue.
    Error:
      type: object
      description: >-
        Simple error. `detail` is a human-readable message (used for auth
        errors).
      properties:
        detail:
          type: string
          example: 'API key required. Use Authorization: Bearer sk-xxx'
  responses:
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            detail: >-
              Invalid or missing API key. Pass it as Authorization: Bearer
              sk-...
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key passed as Bearer token

````