> ## Documentation Index
> Fetch the complete documentation index at: https://docs.slidevid.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrieve Template Details

> Get detailed information about a specific template including scenes and variables

## Overview

Retrieve complete details about a template, including its scenes, script variables, and configuration. This information is essential before generating videos from the template.

<Info>
  Templates in SlideVid work with **scenes** - each scene has a script with `{{variables}}` that you can replace when generating videos.
</Info>

### Path Parameters

<ParamField path="templateId" type="string" required>
  The template ID to retrieve
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.slidevid.ai/v1/template/cmha385y900012yhv17qfmase" \
    -H "x-api-key: your_api_key_here"
  ```

  ```javascript Node.js theme={null}
  const templateId = 'cmha385y900012yhv17qfmase';

  const response = await fetch(`https://api.slidevid.ai/v1/template/${templateId}`, {
    headers: { 'x-api-key': 'your_api_key_here' }
  });

  const template = await response.json().data;
  console.log('Template scenes:', template.scenes.length);
  console.log('Variables needed:', template.variables);
  ```

  ```python Python theme={null}
  import requests

  template_id = 'cmha385y900012yhv17qfmase'

  response = requests.get(
      f'https://api.slidevid.ai/v1/template/{template_id}',
      headers={'x-api-key': 'your_api_key_here'}
  )

  template = response.json()['data']
  print(f'Scenes: {len(template["scenes"])}')
  print(f'Variables: {template["variables"]}')
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "id": "cmha385y900012yhv17qfmase",
      "name": "Product Presentation Template",
      "type": "class",
      "thumbnail": "https://cdn.tryslidevid.ai/thumbnails/template.jpg",
      "isTemplate": true,
      "videoSettings": {
        "aspectRatio": "ratio_16_9",
        "caption": {
          "enabled": true,
          "preset": "wrap1",
          "alignment": "bottom"
        }
      },
      "scenes": [
        {
          "script": "Welcome to our presentation about {{product_name}}. Today we'll discuss {{description_small}}",
          "variables": [
            { "key": "product_name", "type": "text", "value": "AI Video Platform" },
            { "key": "description_small", "type": "text", "value": "automated video creation" },
            { "key": "background_image", "type": "media", "value": "https://cdn.example.com/images/background.jpg" }
          ],
          "avatar": {
            "id": "avatar_sarah_01",
            "topLeft": { "x": 0, "y": 0 },
            "bottomRight": { "x": 640, "y": 720 }
          },
          "caption": {
            "topLeft": { "x": 50, "y": 600 },
            "bottomRight": { "x": 1230, "y": 670 }
          }
        },
        {
          "script": "Our platform offers seamless integration. This is module {{module_number}}",
          "variables": [
            { "key": "module_number", "type": "text", "value": "Module 1" },
            { "key": "feature_image", "type": "media", "value": "https://cdn.example.com/videos/demo.mp4" }
          ],
          "avatar": {
            "id": "avatar_sarah_01",
            "topLeft": { "x": 0, "y": 0 },
            "bottomRight": { "x": 640, "y": 720 }
          },
          "caption": {
            "topLeft": { "x": 50, "y": 600 },
            "bottomRight": { "x": 1230, "y": 670 }
          }
        }
      ],
      "webhook": null,
      "createdAt": "2024-01-15T10:00:00Z",
      "updatedAt": "2024-01-15T10:00:00Z"
    }
  }
  ```
</ResponseExample>

## Understanding Scenes

Templates use **scenes** to structure the video. Each scene contains:

<ParamField body="script" type="string">
  The text for this scene with `{{variable}}` placeholders
</ParamField>

<ParamField body="variables" type="array">
  List of variable objects used in this scene. Each variable has:

  * `key`: The variable name (e.g., "product\_name")
  * `type`: Either "text" (from script/text overlays) or "media" (from image/video/audio overlays)
  * `value`: Example value - text for "text" type (e.g., "John Doe"), URL for "media" type (e.g., "[https://cdn.example.com/image.jpg](https://cdn.example.com/image.jpg)")
</ParamField>

<ParamField body="avatar" type="object">
  Avatar positioning information for this scene

  * `id`: Avatar identifier
  * `topLeft`: Top-left corner coordinates `{x, y}`
  * `bottomRight`: Bottom-right corner coordinates `{x, y}`
</ParamField>

<ParamField body="caption" type="object">
  Caption positioning information for this scene

  * `topLeft`: Top-left corner coordinates `{x, y}`
  * `bottomRight`: Bottom-right corner coordinates `{x, y}`
</ParamField>

### Scene Structure Example

```json Scene Example theme={null}
{
  "script": "Hello {{name}}! Welcome to {{company}}. Today we'll show you {{feature}}.",
  "variables": [
    { "key": "name", "type": "text", "value": "John Doe" },
    { "key": "company", "type": "text", "value": "Acme Corp" },
    { "key": "feature", "type": "text", "value": "AI automation" },
    { "key": "background_image", "type": "media", "value": "https://cdn.example.com/images/office.jpg" },
    { "key": "intro_music", "type": "media", "value": "https://cdn.example.com/audio/upbeat.mp3" }
  ],
  "avatar": {
    "id": "avatar_sarah_01",
    "topLeft": { "x": 0, "y": 0 },
    "bottomRight": { "x": 640, "y": 720 }
  },
  "caption": {
    "topLeft": { "x": 50, "y": 600 },
    "bottomRight": { "x": 1230, "y": 670 }
  }
}
```

<Info>
  **Variable Types:**

  * **`type: "text"`**: Variables from script (`{{name}}`, `{{company}}`) or text overlays
  * **`type: "media"`**: Variables from image/video/audio overlays (set via `variableName` property)

  When generating videos, provide values based on type:

  * Text variables: Provide the text content (e.g., "John Doe", "Acme Corp")
  * Media variables: Provide URLs (e.g., "[https://cdn.example.com/image.jpg](https://cdn.example.com/image.jpg)")
</Info>

## Variable Extraction

The API automatically extracts variables from each scene:

<CodeGroup>
  ```javascript Extract Variables theme={null}
  const template = await getTemplateDetails(templateId);

  // Variables per scene
  template.scenes.forEach((scene, index) => {
    console.log(`Scene ${index + 1}:`);
    scene.variables.forEach(v => {
      console.log(`  - ${v.key} (${v.type})`);
    });
  });

  // Get all unique variable keys across all scenes
  const allVariableKeys = new Set();
  template.scenes.forEach(scene => {
    scene.variables.forEach(v => allVariableKeys.add(v.key));
  });
  console.log('All unique variable keys:', Array.from(allVariableKeys));
  ```

  ```python Extract Variables theme={null}
  template = get_template_details(template_id)

  # Variables per scene
  for i, scene in enumerate(template['scenes']):
      print(f'Scene {i + 1}:')
      for v in scene['variables']:
          print(f'  - {v["key"]} ({v["type"]})')

  # Get all unique variable keys across all scenes
  all_variable_keys = set()
  for scene in template['scenes']:
      for v in scene['variables']:
          all_variable_keys.add(v['key'])
  print('All unique variable keys:', list(all_variable_keys))
  ```
</CodeGroup>

## Use Cases

<AccordionGroup>
  <Accordion title="Preview Before Generation" icon="eye">
    View the template structure and required variables before creating videos

    ```javascript theme={null}
        const template = await getTemplate(templateId);
        template.scenes.forEach((scene, i) => {
          const varList = scene.variables.map(v => `${v.key} (${v.type})`).join(', ');
          console.log(`Scene ${i + 1} needs: ${varList}`);
        });
    ```
  </Accordion>

  <Accordion title="Dynamic Form Generation" icon="input-text">
    Build a UI form dynamically based on template variables

    ```javascript theme={null}
        template.scenes.forEach((scene, index) => {
          scene.variables.forEach(variable => {
            // Create appropriate input based on type
            if (variable.type === 'text') {
              createTextInput(variable.key, `scene-${index}`);
            } else if (variable.type === 'media') {
              createUrlInput(variable.key, `scene-${index}`);
            }
          });
        });
    ```
  </Accordion>

  <Accordion title="Validation" icon="shield-check">
    Validate that you have all required data for each scene before generation

    ```javascript theme={null}
        const errors = [];
        template.scenes.forEach((scene, index) => {
          const missingVars = scene.variables.filter(v => !sceneData[index][v.key]);
          if (missingVars.length > 0) {
            const varList = missingVars.map(v => v.key).join(', ');
            errors.push(`Scene ${index + 1} missing: ${varList}`);
          }
        });
        if (errors.length > 0) {
          throw new Error(errors.join('\n'));
        }
    ```
  </Accordion>

  <Accordion title="Batch Processing" icon="layer-group">
    Process multiple records with the same template

    ```javascript theme={null}
    const template = await getTemplate(templateId);

    for (const customer of customers) {
      await generateVideo(templateId, {
        name: customer.name,
        product: customer.subscriptionPlan,
        // ... map other variables
      });
    }
    ```
  </Accordion>
</AccordionGroup>

## Complete Example

```javascript Complete Workflow theme={null}
// 1. Get template details
const response = await fetch(
  `https://api.slidevid.ai/v1/template/${templateId}`,
  { headers: { 'x-api-key': API_KEY } }
);

const template = await response.json().data;

// 2. Check what variables are needed per scene
console.log('Template:', template.name);
console.log('Scenes:', template.scenes.length);
template.scenes.forEach((scene, i) => {
  console.log(`Scene ${i + 1} variables:`);
  scene.variables.forEach(v => {
    console.log(`  - ${v.key} (${v.type})`);
  });
});

// 3. Prepare your data for each scene
const scenesData = [
  {
    product_name: 'AI Video Platform',
    description_small: 'the key features of our product',
    background_image: 'https://cdn.example.com/bg1.jpg'
  },
  {
    module_number: '1',
    feature_image: 'https://cdn.example.com/feature.jpg'
  }
];

// 4. Validate you have all variables for each scene
const errors = [];
template.scenes.forEach((scene, index) => {
  const missingVars = scene.variables.filter(v => !scenesData[index][v.key]);
  if (missingVars.length > 0) {
    const varList = missingVars.map(v => v.key).join(', ');
    errors.push(`Scene ${index + 1} missing: ${varList}`);
  }
});

if (errors.length > 0) {
  throw new Error(errors.join('\n'));
}

// 5. Generate video (see next endpoint)
await generateVideoFromTemplate(templateId, scenesData);
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Generate from Template" icon="play" href="/api-reference/template/generate">
    Create a video using this template
  </Card>

  <Card title="List Templates" icon="list" href="/api-reference/template/list">
    Browse all your templates
  </Card>
</CardGroup>


## OpenAPI

````yaml GET /v1/template/{templateId}
openapi: 3.0.0
info:
  title: SlideVid API
  version: 1.0.0
  description: AI Video Generation API
servers:
  - url: https://api.slidevid.ai
security:
  - ApiKeyAuth: []
paths:
  /v1/template/{templateId}:
    get:
      tags: []
      summary: Retrieve Template Details
      description: >-
        Get detailed information about a specific template including scenes and
        variables
      operationId: getTemplateDetails
      parameters:
        - name: templateId
          in: path
          description: Template ID
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
      security:
        - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````