Skip to main content

​
Overview

Generate videos from templates by providing variable values for each scene. This is perfect for creating personalized video content at scale.

​
How Templates Work

Templates in Hooked use scenes - each scene has a script with {{variables}} that you replace:
  1. Get template details to see scenes and variables
  2. Prepare your data with values for each variable per scene
  3. Generate video with the templateId and scenes array

​
Request Body

​
type
string
required
Video type (must match template type). Use class for template-based videos.
​
templateId
string
required
The template ID to use (1-20 characters)
​
title
string
required
Video title (1-100 characters)
​
caption
boolean
required
Enable auto-generated captions
​
language
string
required
Language code for the video (max 2 characters). Example: en, es, fr
​
scenes
array
required
Array of scenes (1-20 scenes). Each scene contains:
​
webhook
string
URL to receive completion notification (max 500 characters)
​
metadata
object
Custom data to pass through to webhook responses. Use this to correlate videos with your internal systems (e.g., course IDs, user IDs, order numbers). Maximum size: 5KB.
{
  "courseId": "python-101",
  "lessonId": "lesson-5",
  "studentId": "student-123"
}

​
Scene Structure

Each scene in the scenes array must include:
​
script
string
required
The script for this scene (can include {{variables}})
​
variables
array
required
Array of {key, type, value} pairs to replace in the script
[
  {"key": "name", "type": "text", "value": "John Doe"},
  {"key": "product", "type": "text", "value": "AI Video Tool"}
]

curl -X POST "https://api.tryhooked.ai/v1/project/create" \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_api_key_here" \
  -d '{
    "type": "class",
    "templateId": "cmha385y900012yhv17qfmase",
    "title": "My Video from Template",
    "caption": true,
    "language": "en",
    "scenes": [
      {
        "script": "Welcome to our presentation. Today we'\''ll discuss the key features of our product.",
        "avatar": {
          "id": "1",
          "topLeft": { "x": 0, "y": 0 },
          "bottomRight": { "x": 100, "y": 100 }
        },
        "variables": [
          {"key": "name", "type": "text", "value": "Juan Montiel"},
          {"key": "description_small", "type": "text", "value": "Welcome to our presentation."},
          {"key": "background", "type": "media", "value": "https://example.com/background.jpg"}
        ],
        "voice": "voice_abc123"
      },
      {
        "script": "Our platform offers seamless integration with your existing tools and workflows.",
        "variables": [
          {"key": "module_number", "type": "text", "value": "1"}
        ],
        "voice": "voice_abc123"
      }
    ],
    "webhook": "https://yoursite.com/webhook",
    "metadata": {
      "courseId": "python-101",
      "lessonId": "lesson-5"
    }
  }'

{
  "success": true,
  "message": "Project created successfully",
  "data": {
    "projectId": "proj_new_xyz789",
    "status": "processing",
  }
}

​
Bulk Generation Example

Generate personalized videos for multiple customers:
Bulk Generation
const API_KEY = process.env.HOOKED_API_KEY;
const TEAM_ID = process.env.HOOKED_TEAM_ID;

const template = await getTemplateDetails(templateId);

const customers = [
  { id: 'cust_1', name: 'John Doe', company: 'Acme Corp', plan: 'Pro' },
  { id: 'cust_2', name: 'Jane Smith', company: 'TechStart', plan: 'Enterprise' },
  { id: 'cust_3', name: 'Bob Wilson', company: 'Digital Inc', plan: 'Starter' }
];

for (const customer of customers) {
  // Map template scenes with customer data
  const scenes = template.scenes.map(scene => ({
    script: scene.script,
    avatar: { id: "1" },
    variables: scene.variables.map(v => ({
      key: v.key,
      type: v.type,
      value: customer[v.key] || v.value
    })),
    voice: 'voice_abc123'
  }));

  // Generate video
  const response = await fetch('https://api.tryhooked.ai/v1/project/create', {
    method: 'POST',
    headers: {
      'x-api-key': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      type: template.type,
      templateId: templateId,
      title: `Video for ${customer.name}`,
      caption: true,
      language: 'en',
      scenes: scenes,
      webhook: 'https://yoursite.com/webhook',
      metadata: {
        customerId: customer.id,
        customerName: customer.name
      }
    })
  });

  console.log(`Video created for ${customer.name}`);

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

​
Variable Replacement Rules

Variables in scripts use double curly brackets: {{variable_name}}
"Hello {{first_name}}! Welcome to {{company_name}}."
Variable names are case-sensitive:
  • {{name}} ≠ {{Name}}
  • {{firstName}} ≠ {{firstname}}
You must provide values for all variables in each scene:
// ❌ Will fail if scene has {{name}} and {{product}}
"variables": [
  {"key": "name", "value": "John"}
]

// ✅ Correct
"variables": [
  {"key": "name", "value": "John"},
  {"key": "product", "value": "AI Tool"}
]
Empty string values are allowed:
{"key": "optional_field", "value": ""}
This replaces {{optional_field}} with an empty string.

​
Overriding Template Settings

You can override some template settings: 
{
  "templateId": "...",
  "caption": true,
  "scenes": [...]
}

​
Best Practices

Validate First

Get template details and validate your data before generating

Use Webhooks

Always provide webhook URLs for async notification

Rate Limiting

Add delays between bulk requests (1 second recommended)

Error Handling

Check for missing variables before generation
Missing Variables: If any required variable is missing, the video generation will fail. Always validate your data against the template’s variable requirements first.

​
API Limits

LimitValue
Max scenes per project20
Max script length per scene5,000 characters
Max variables per scene20
Max variable key length100 characters
Max variable value length2,000 characters
Max title length200 characters
Max webhook URL length500 characters
Max metadata size5KB

Template Details

Get template structure and variables

List Templates

Browse available templates

List Videos

View your generated videos