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

# List Templates

> Get all project templates with customizable variables

## Overview

Templates are pre-configured projects that allow you to create videos by replacing variables like `{{name}}`, `{{product}}`, etc.

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

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.slidevid.ai/v1/template/list', {
    headers: { 'x-api-key': 'your_api_key_here' }
  });
  const { templates } = await response.json().data;
  ```

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

  response = requests.get(
      'https://api.slidevid.ai/v1/template/list',
      headers={'x-api-key': 'your_api_key_here'}
  )
  templates = response.json()['data']['templates']
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "templates": [
        {
          "id": "cmha385y900012yhv17qfmase",
          "name": "Product Demo 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": "Hi {{first_name}}! Check out our {{product_name}}. It's perfect for {{use_case}}.",
              "variables": [
                { "key": "first_name", "type": "text", "value": "Sarah" },
                { "key": "product_name", "type": "text", "value": "SlideVid Pro" },
                { "key": "use_case", "type": "text", "value": "creating sales videos" },
                { "key": "background_image", "type": "media", "value": "https://cdn.example.com/images/product-bg.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": "With features like {{feature_1}} and {{feature_2}}, you'll achieve {{benefit}}.",
              "variables": [
                { "key": "feature_1", "type": "text", "value": "AI voiceovers" },
                { "key": "feature_2", "type": "text", "value": "auto captions" },
                { "key": "benefit", "type": "text", "value": "10x faster video production" }
              ],
              "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"
        }
      ],
      "total": 1
    }
  }
  ```
</ResponseExample>

## Using Templates

Once you have a template, you can create videos by replacing the variables:

### Step 1: Get Template Details

```javascript theme={null}
// Get template with scenes and variables
const template = templates[0];
console.log('Template:', template.name);
console.log('Scenes:', template.scenes.length);

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

// Get all unique variable keys if needed
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));
```

### Step 2: Understanding Scene Structure

Each scene contains:

* **script**: The narration text with `{{variables}}`
* **variables**: Array of variable objects, each with:
  * `key`: Variable name (e.g., "first\_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)")
* **avatar**: Position and ID of the avatar (if any)
* **caption**: Position of captions (if enabled)

<Info>
  **Variable Types:**

  * **`type: "text"`**: From script (`{{first_name}}`) or text overlays
  * **`type: "media"`**: From image/video/audio overlays (via `variableName` property)
</Info>

### Step 3: Create Video from Template

```javascript theme={null}
const response = await fetch('https://api.slidevid.ai/v1/template/generate', {
  method: 'POST',
  headers: {
    'x-api-key': 'your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    templateId: template.id,
    scenes: [
      {
        variables: [
          { key: 'first_name', value: 'John', type: 'text' },
          { key: 'product_name', value: 'AI Video Generator', type: 'text' },
          { key: 'use_case', value: 'creating marketing content', type: 'text' },
          { key: 'background_image', value: 'https://cdn.example.com/bg1.jpg', type: 'media' }
        ]
      },
      {
        variables: [
          { key: 'feature_1', value: 'automated editing', type: 'text' },
          { key: 'feature_2', value: 'AI voices', type: 'text' },
          { key: 'benefit', value: 'save 10 hours per week', type: 'text' }
        ]
      }
    ],
    webhook: 'https://yoursite.com/webhook'
  })
});
```

The system will:

1. Load the template with all scenes
2. Replace text variables in scripts and overlays
3. Replace media variables (images, videos, audio) with provided URLs
4. Apply avatar and caption positioning from template
5. Generate the video

## Variable Format

Variables in templates use double curly brackets: `{{variable_name}}`

**Example script:**

```
Hello {{name}}! 

We're excited to show you {{product}}. 
It's been helping {{customer_count}} customers achieve {{benefit}}.

Try it today at {{website}}!
```

**Variables to replace:**

* `name`
* `product`
* `customer_count`
* `benefit`
* `website`

## Creating Templates

<Note>
  Templates are currently created through the SlideVid dashboard. API creation will be available soon.
</Note>

To create a template:

1. Create a project in the dashboard
2. Use `{{variable}}` syntax in your script
3. Mark the project as a template
4. The template will appear in the API

## Use Cases

<AccordionGroup>
  <Accordion title="Personalized Marketing" icon="envelope">
    Create personalized video messages for each customer:

    ```
    Hi {{customer_name}}, 
    Thanks for being with us for {{days}} days!
    ```
  </Accordion>

  <Accordion title="Product Demos" icon="box">
    Generate product demos with different features:

    ```
    Meet {{product}}, the solution for {{problem}}.
    Key feature: {{feature}}
    ```
  </Accordion>

  <Accordion title="Educational Content" icon="graduation-cap">
    Create course content at scale:

    ```
    Welcome to {{course_name}}, Lesson {{lesson_number}}.
    Today we'll cover {{topic}}.
    ```
  </Accordion>

  <Accordion title="Real Estate Tours" icon="house">
    Generate property tour videos:

    ```
    Welcome to {{address}}, a {{bedrooms}} bedroom home.
    Price: {{price}}. Contact {{agent}}.
    ```
  </Accordion>
</AccordionGroup>

## Best Practices

<Tip>
  **Keep variable names descriptive**: Use `customer_name` instead of just `name` for clarity
</Tip>

<Tip>
  **Test with sample data**: Always test your template with sample variables before production
</Tip>

<Tip>
  **Document your variables**: Keep track of what variables each template expects
</Tip>

<Warning>
  **All variables must be provided**: If a variable in the template is not provided in the API call, the video generation will fail
</Warning>

## Example: Bulk Personalized Videos

```javascript theme={null}
// Get your template
const response = await fetch('https://api.slidevid.ai/v1/template/list', {
  headers: { 'x-api-key': API_KEY }
});
const { templates } = await response.json().data;
const template = templates[0];

// Customer list with data for each scene
const customers = [
  {
    name: 'John',
    product: 'Pro Plan',
    benefit: 'unlimited videos',
    photo: 'https://cdn.example.com/john-photo.jpg'
  },
  {
    name: 'Sarah',
    product: 'Starter Plan',
    benefit: '50 videos/month',
    photo: 'https://cdn.example.com/sarah-photo.jpg'
  },
  {
    name: 'Mike',
    product: 'Enterprise',
    benefit: 'custom solutions',
    photo: 'https://cdn.example.com/mike-photo.jpg'
  }
];

// Generate personalized video for each customer
for (const customer of customers) {
  // Build scenes with variables
  const scenes = template.scenes.map((sceneTemplate, index) => {
    // Map customer data to scene variables
    const variables = [];

    // Check each variable in the scene template
    sceneTemplate.variables.forEach(templateVar => {
      if (templateVar.key === 'name') {
        variables.push({ key: 'name', value: customer.name, type: 'text' });
      }
      if (templateVar.key === 'product') {
        variables.push({ key: 'product', value: customer.product, type: 'text' });
      }
      if (templateVar.key === 'benefit') {
        variables.push({ key: 'benefit', value: customer.benefit, type: 'text' });
      }
      if (templateVar.key === 'customer_photo') {
        variables.push({
          key: 'customer_photo',
          value: customer.photo,
          type: 'media'
        });
      }
    });

    return { variables };
  });

  await fetch('https://api.slidevid.ai/v1/template/generate', {
    method: 'POST',
    headers: {
      'x-api-key': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      templateId: template.id,
      scenes,
      webhook: `https://yoursite.com/webhook/${customer.id}`
    })
  });

  // Rate limiting - wait 1 second between requests
  await new Promise(resolve => setTimeout(resolve, 1000));
}
```

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Template Details" icon="info-circle" href="/api-reference/template/details">
    Get detailed information about a specific template
  </Card>

  <Card title="Generate from Template" icon="play" href="/api-reference/template/generate">
    Create a video from a template
  </Card>

  <Card title="List Avatars" icon="user" href="/api-reference/avatar/list">
    Browse available avatars for templates
  </Card>

  <Card title="List Voices" icon="microphone" href="/api-reference/voice/list">
    Browse available voices for templates
  </Card>
</CardGroup>


## OpenAPI

````yaml GET /v1/template/list
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/list:
    get:
      tags: []
      summary: List Templates
      description: Get all project templates with customizable variables
      operationId: listTemplates
      responses:
        '200':
          description: Success
      security:
        - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````