Skip to main content

​
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

const response = await fetch('https://api.tryhooked.ai/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

const createTutorial = async () => {
  const response = await fetch('https://api.tryhooked.ai/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

const createTransitionVideo = async () => {
  const response = await fetch('https://api.tryhooked.ai/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

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: Leverage start/end frame scenes for impressive visual effects between static images.

​
Scene Types

TypeDescriptionRequired Fields
avatarTalking avatar scenescript, avatarId, voiceId
videoVideo/image clipmediaId
picture_in_pictureAvatar over video/imagescript, avatarId, voiceId, mediaId
start_end_frameAI-generated transitionstartFrameMediaId, endFrameMediaId, framePrompt, frameModel, frameDuration

​
AI Models for Transitions

ModelDescriptionBest For
kling_2_5Kling 2.5 modelFast generation, general transitions
veo_3_1Google Veo 3.1High 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

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