Scenes Example

Overview

Scenes lets you build a video as a storyboard: a list of scenes, each of a different type, played in order. Combine talking avatars, your own clips, avatars over a screen recording and AI-generated transitions. It works well for tutorials, marketing videos, educational content and stories told in several parts. Each scene needs a type; scenes play in the order you list them. Avatar IDs come from GET /v1/avatar/list, voice IDs from GET /v1/voice/list, and every mediaId, startFrameMediaId and endFrameMediaId must be a file from your own Hooked library (any other ID answers 400, e.g. scenes.0.mediaId: Media "abc" not found.).

Basic Multi-Scene Video

A video scene plays one of your clips. Add a script and a voiceId to narrate it. The narration of video scenes is only played when every scene of the project is a video scene, as here.

const response = await fetch('https://api.hooked.so/v1/project/create/scenes', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.HOOKED_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Getting Started Tutorial',
    scenes: [
      {
        type: 'video',
        mediaId: 'clxmedia0001'
      },
      {
        type: 'video',
        script: 'Welcome to our product demo! Let me show you how it works.',
        mediaId: 'clxmedia0002',
        voiceId: '1000'
      }
    ],
    webhook: 'https://yoursite.com/hooked-webhook?token=YOUR_SECRET'
  })
});

const { data } = await response.json();
console.log('Project ID:', data.projectId); // follow it with GET /v1/project/{projectId}

Tutorial with Picture in Picture

A picture_in_picture scene puts the avatar, cut out from its background, over your media. Avatar and picture-in-picture scenes speak the script in the avatar’s own voice, so they take no voiceId.

const createTutorial = async () => {
  const response = await fetch('https://api.hooked.so/v1/project/create/scenes', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.HOOKED_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Getting Started Tutorial',
      scenes: [
        {
          type: 'picture_in_picture',
          script: 'First, click on the settings icon in the top right corner.',
          avatarId: '1',
          mediaId: 'clxmedia0003'
        },
        {
          type: 'picture_in_picture',
          script: 'Then, open the integrations tab and turn on API access.',
          avatarId: '1',
          mediaId: 'clxmedia0004'
        }
      ],
      musicId: '1',
      aspectRatio: 'ratio_16_9',
      caption: {
        preset: 'modern',
        alignment: 'bottom',
        disabled: false
      },
      language: 'en',
      webhook: 'https://yoursite.com/hooked-webhook?token=YOUR_SECRET',
      metadata: {
        tutorialId: 'getting-started',
        version: '1.0'
      }
    })
  });

  return await response.json();
};

AI Transition Video

A start_end_frame scene generates a clip that starts on one of your images and, optionally, ends on another. It needs startFrameMediaId, framePrompt, frameDuration (seconds) and frameModel (veo_3_1, seedance_2_0 or kling_3_0); endFrameMediaId is optional. To narrate it, add a script and a voiceId (and voiceSettings if you want): the clip then lasts as long as the narration.

const createTransitionVideo = async () => {
  const response = await fetch('https://api.hooked.so/v1/project/create/scenes', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.HOOKED_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Before and After',
      scenes: [
        {
          type: 'avatar',
          script: 'Watch this transformation!',
          avatarId: '1'
        },
        {
          type: 'start_end_frame',
          startFrameMediaId: 'clxmedia0005',
          endFrameMediaId: 'clxmedia0006',
          frameModel: 'veo_3_1',
          framePrompt: 'Smooth morphing transition from the before state to the after state with elegant camera movement',
          frameDuration: 5
        },
        {
          type: 'avatar',
          script: 'Incredible, right? This is what our product does.',
          avatarId: '1'
        }
      ],
      aspectRatio: 'ratio_9_16',
      caption: {
        preset: 'modern',
        alignment: 'bottom',
        disabled: false
      },
      language: 'en',
      webhook: 'https://yoursite.com/hooked-webhook?token=YOUR_SECRET',
      metadata: { campaign: 'before-after' }
    })
  });

  return await response.json();
};

Getting the Video

The create call answers right away with { success: true, data: { projectId, status }, message }. Then wait for your webhook or poll the project:

async function waitForVideo(projectId) {
  while (true) {
    const res = await fetch(`https://api.hooked.so/v1/project/${projectId}`, {
      headers: { 'x-api-key': process.env.HOOKED_API_KEY }
    });
    const { data } = await res.json();

    if (data.video?.status === 'COMPLETED') return data.video.url;
    if (data.status === 'failed' || data.video?.status === 'FAILED') {
      throw new Error(data.video?.message || data.message || 'Video failed');
    }

    await new Promise((resolve) => setTimeout(resolve, 15000)); // every ~15 s
  }
}

The render starts as soon as the project is completed; video fills in a minute or two later.

Send an Idempotency-Key header to retry safely: if a request times out or answers 5xx, sending it again with the same key and body returns the first answer instead of creating (and charging) the project twice.

Teams in bring-your-own-keys mode are not charged credits for generation but need their own provider keys in Settings → AI keys: OpenRouter always, ElevenLabs when a video or start_end_frame scene is narrated, Gemini when there is an avatar or picture-in-picture scene, and Bria for picture-in-picture. A missing key answers 402 with code: "missing_credentials" and the list in missingProviders, before anything is created. Managed teams pay 13 credits per project, plus 100 per started 15 seconds of script (about 2.5 words per second) for each avatar and picture-in-picture scene and each narrated video scene, plus the transition model’s per-second rate for each start_end_frame scene (for the narration’s length when it is narrated).

Tips for Scenes Videos

Plan Your Storyboard: Outline your scenes before creating. Each scene should serve a clear purpose in the narrative.

Consistent Avatar: Use the same avatar across scenes for continuity, unless intentionally switching perspectives.

Vary Scene Types: Mix avatar, video, and PiP scenes to keep viewers engaged and add visual variety.

Smooth Transitions: Write scripts that flow naturally between scenes. End one scene leading into the next.

Optimize Duration: Keep individual scenes focused. Split long content into multiple shorter scenes.

Use AI Transitions: Use start/end frame scenes for visual effects between still images.

Scene Types

Type	Description	Required Fields	Optional
`avatar`	Talking avatar, speaking in its own voice	`script`, `avatarId`	—
`video`	One of your clips or images	`mediaId`	`script` + `voiceId` (narration), `voiceSettings`
`picture_in_picture`	Avatar cut out over your media	`script`, `avatarId`, `mediaId`	—
`start_end_frame`	AI-generated clip between frames	`startFrameMediaId`, `framePrompt`, `frameDuration`, `frameModel`	`endFrameMediaId`, `script` + `voiceId` (+ `voiceSettings`)

Up to 50 scenes per project. Scripts are up to 5,000 characters per scene.

Other Fields

Field	Default	Description
`name`	generated	Project name
`aspectRatio`	`ratio_9_16`	`ratio_9_16`, `ratio_16_9` or `ratio_1_1`
`caption`	`{ preset: 'modern', alignment: 'bottom', disabled: false }`	Captions are on unless `disabled: true`
`language`	detected	Two-letter language code
`content.brandingLogo`	—	Your logo over the video: `{ enabled, url, position, size }`
`musicId`	—	Background music from `GET /v1/music/list`
`webhook`	—	HTTPS URL called when the video is ready or the project fails
`metadata`	—	Your own object (up to 5 KB), sent back in the webhook

AI Models for Transitions

`frameModel`	Model
`veo_3_1`	Google Veo 3.1 (Fast)
`seedance_2_0`	Seedance 2.0
`kling_3_0`	Kling 3.0

The older values kling_2_5 and seedance_1_5 are no longer available and answer 400.

Use Cases

Tutorials: Combine avatar explanations with screen recordings and demos
Marketing Videos: Mix talking head with product shots and lifestyle footage
Educational Content: Alternate between instructor and visual demonstrations
Storytelling: Create narrative videos with multiple scenes and perspectives
Before/After: Use AI transitions to show transformations

Handling the Webhook Response

Webhooks are signed: check the Hooked-Signature header as shown in Webhooks. Answer 200 quickly; Hooked tries 3 times with a 10-second timeout.

// Express.js webhook handler
app.post('/hooked-webhook', express.json(), (req, res) => {
  if (req.query.token !== process.env.HOOKED_WEBHOOK_TOKEN) {
    return res.status(401).send('Unauthorized');
  }

  const { status, message, data } = req.body;
  const { videoId, projectId, url, metadata } = data;

  if (status === 'COMPLETED') {
    console.log('Video ready:', url, 'project:', projectId, 'video:', videoId);
    console.log('Your metadata:', metadata);
    // Save to your database, notify team, etc.
  } else if (status === 'FAILED' && videoId === null) {
    console.error('Project failed before it rendered:', projectId, message);
  } else if (status === 'FAILED') {
    console.error('Render failed:', projectId, videoId, message);
  }

  res.status(200).send('OK');
});

Getting Started

Core Concepts

AI Agents

Guides

Examples

Overview

Basic Multi-Scene Video

Tutorial with Picture in Picture

AI Transition Video

Getting the Video

Tips for Scenes Videos

Scene Types

Other Fields

AI Models for Transitions

Use Cases

Handling the Webhook Response

​Overview

​Basic Multi-Scene Video

​Tutorial with Picture in Picture

​AI Transition Video

​Getting the Video

​Tips for Scenes Videos

​Scene Types

​Other Fields

​AI Models for Transitions

​Use Cases

​Handling the Webhook Response

Overview

Basic Multi-Scene Video

Tutorial with Picture in Picture

AI Transition Video

Getting the Video

Tips for Scenes Videos

Scene Types

Other Fields

AI Models for Transitions

Use Cases

Handling the Webhook Response