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

# Scenes Example

> Create multi-scene videos combining avatars, video clips, and AI-generated transitions

## Overview

Scenes allows you to create complex, multi-scene videos by combining different content types in a storyboard format. Perfect for tutorials, marketing videos, educational content, and storytelling with multiple segments.

## Basic Multi-Scene Video

```javascript theme={null}
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',
        script: 'Welcome to our product demo! Let me show you how it works.',
        mediaId: 'product_demo_video_id'
      },
      {
        type: 'video',
        script: 'Welcome to our product demo! Let me show you how it works.',
        mediaId: 'product_demo_video_id',
        voiceId: 'warm_voice_id'
      }
    ]
  })
});

const data = await response.json();
console.log('Project ID:', data.projectId);
```

## Tutorial with Picture in Picture

```javascript theme={null}
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: 'friendly_avatar_id',
          voiceId: 'warm_voice_id',
          mediaId: 'settings_screenshot_id'
        },
        {
          type: 'picture_in_picture',
          script: 'Then, navigate to the integrations tab and enable the API access.',
          avatarId: 'friendly_avatar_id',
          voiceId: 'warm_voice_id',
          mediaId: 'integrations_screenshot_id'
        }
      ],
      musicId: 'upbeat_background_id',
      aspectRatio: 'ratio_16_9',
      caption: {
        preset: 'modern',
        alignment: 'bottom',
        disabled: false
      },
      language: 'en',
      addStickers: false,
      webhook: 'https://yoursite.com/webhook',
      metadata: {
        tutorialId: 'getting-started',
        version: '1.0'
      }
    })
  });

  return await response.json();
};
```

## AI Transition Video

```javascript theme={null}
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: 'Getting Started Tutorial',
      scenes: [
        {
          type: 'avatar',
          script: 'Watch this amazing transformation!',
          avatarId: 'energetic_avatar_id',
          voiceId: 'excited_voice_id'
        },
        {
          type: 'start_end_frame',
          startFrameMediaId: 'before_image_id',
          endFrameMediaId: 'after_image_id',
          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 the power of our solution.',
          avatarId: 'energetic_avatar_id',
          voiceId: 'excited_voice_id'
        }
      ],
      musicId: 'upbeat_background_id',
      aspectRatio: 'ratio_16_9',
      caption: {
        preset: 'modern',
        alignment: 'bottom',
        disabled: false
      },
      language: 'en',
      addStickers: false,
      webhook: 'https://yoursite.com/webhook',
      metadata: {
        tutorialId: 'getting-started',
        version: '1.0'
      }
    })
  });

  return await response.json();
};
```

## Tips for Scenes Videos

<Tip>**Plan Your Storyboard**: Outline your scenes before creating. Each scene should serve a clear purpose in the narrative.</Tip>
<Tip>**Consistent Avatar**: Use the same avatar across scenes for continuity, unless intentionally switching perspectives.</Tip>
<Tip>**Vary Scene Types**: Mix avatar, video, and PiP scenes to keep viewers engaged and add visual variety.</Tip>
<Tip>**Smooth Transitions**: Write scripts that flow naturally between scenes. End one scene leading into the next.</Tip>
<Tip>**Optimize Duration**: Keep individual scenes focused. Split long content into multiple shorter scenes.</Tip>
<Tip>**Use AI Transitions**: Leverage start/end frame scenes for impressive visual effects between static images.</Tip>

## Scene Types

| Type                 | Description             | Required Fields                                                                      |
| -------------------- | ----------------------- | ------------------------------------------------------------------------------------ |
| `avatar`             | Talking avatar scene    | `script`, `avatarId`, `voiceId`                                                      |
| `video`              | Video/image clip        | `mediaId`                                                                            |
| `picture_in_picture` | Avatar over video/image | `script`, `avatarId`, `voiceId`, `mediaId`                                           |
| `start_end_frame`    | AI-generated transition | `startFrameMediaId`, `endFrameMediaId`, `framePrompt`, `frameModel`, `frameDuration` |

## AI Models for Transitions

| Model       | Description     | Best For                               |
| ----------- | --------------- | -------------------------------------- |
| `kling_2_5` | Kling 2.5 model | Fast generation, general transitions   |
| `veo_3_1`   | Google Veo 3.1  | High quality, complex camera movements |

***

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

## Handling the Webhook Response

```javascript theme={null}
// Express.js webhook handler
app.post('/webhook', (req, res) => {
  const { data, status, message } = req.body;

  if (status === "COMPLETED") {
    const { videoId, status: videoStatus, url, shareUrl, metadata } = data;
    console.log('Scenes video completed!');
    console.log('Video ID:', videoId);
    console.log('Download URL:', url);
    console.log('Share URL:', shareUrl);
    console.log('Tutorial ID:', metadata.tutorialId);

    // Save to your database, notify team, etc.
  }

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