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