Retrieve Template Details

Overview

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

Templates in SlideVid work with scenes - each scene has a script with {{variables}} that you can replace when generating videos.

Path Parameters

templateId

string

required

The template ID to retrieve

curl -X GET "https://api.slidevid.ai/v1/template/cmha385y900012yhv17qfmase" \
  -H "x-api-key: your_api_key_here"

{
  "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"
  }
}

Understanding Scenes

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

script

string

The text for this scene with {{variable}} placeholders

variables

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”)

avatar

object

Avatar positioning information for this scene

id: Avatar identifier
topLeft: Top-left corner coordinates {x, y}
bottomRight: Bottom-right corner coordinates {x, y}

caption

object

Caption positioning information for this scene

topLeft: Top-left corner coordinates {x, y}
bottomRight: Bottom-right corner coordinates {x, y}

Scene Structure Example

Scene Example

{
  "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 }
  }
}

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”)

Variable Extraction

The API automatically extracts variables from each scene:

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));

Use Cases

Preview Before Generation

View the template structure and required variables before creating videos

    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}`);
    });

Dynamic Form Generation

Build a UI form dynamically based on template variables

    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}`);
        }
      });
    });

Validation

Validate that you have all required data for each scene before generation

    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'));
    }

Batch Processing

Process multiple records with the same template

const template = await getTemplate(templateId);

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

Complete Example

Complete Workflow

// 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

Generate from Template

Create a video using this template

List Templates

Browse all your templates

Authorizations

x-api-key

string

header

required

Path Parameters

templateId

string

required

Template ID

Response

200

Success

Getting Started

Resources

Videos

Templates

Overview

Path Parameters

Understanding Scenes

Scene Structure Example

Variable Extraction

Use Cases

Complete Example

Next Steps

Generate from Template

List Templates

Authorizations

Path Parameters

Response

Getting Started

Resources

Videos

Templates

​Overview

​Path Parameters

​Understanding Scenes

​Scene Structure Example

​Variable Extraction

​Use Cases

​Complete Example

​Next Steps

Generate from Template

List Templates

Authorizations

Path Parameters

Response

Overview

Path Parameters

Understanding Scenes

Scene Structure Example

Variable Extraction

Use Cases

Complete Example

Next Steps