Skip to main content
POST
/
v1
/
project
/
create
/
scenes
Create Scenes Video
curl --request POST \
  --url https://b8e35428b2f8.ngrok-free.app/api/v1/project/create/scenes \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "name": "Product Tutorial",
  "scenes": [
    {
      "type": "avatar",
      "script": "Welcome to our product demo! Let me show you how it works.",
      "avatarId": "professional_avatar_id",
      "voiceId": "confident_voice_id"
    },
    {
      "type": "video",
      "mediaId": "product_demo_video_id"
    },
    {
      "type": "start_end_frame",
      "startFrameMediaId": "start_image_id",
      "endFrameMediaId": "end_image_id",
      "frameModel": "veo_3_1",
      "framePrompt": "Smooth camera zoom out revealing the full scene",
      "frameDuration": 5
    },
    {
      "type": "picture_in_picture",
      "script": "As you can see here, the interface is intuitive and easy to use.",
      "avatarId": "professional_avatar_id",
      "voiceId": "confident_voice_id",
      "mediaId": "screenshot_id"
    },
    {
      "type": "avatar",
      "script": "Try it today and see the difference!",
      "avatarId": "professional_avatar_id",
      "voiceId": "confident_voice_id"
    }
  ],
  "musicId": "upbeat_background_id",
  "aspectRatio": "ratio_9_16",
  "caption": {
    "preset": "modern",
    "alignment": "bottom",
    "disabled": false
  },
  "addStickers": false,
  "audio": {
    "speed": 1,
    "stability": 0.5,
    "similarityBoost": 0.75,
    "style": 0,
    "useSpeakerBoost": true
  },
  "language": "en",
  "webhook": "https://yoursite.com/webhook",
  "metadata": {
    "tutorialId": "getting-started",
    "version": "1.0"
  }
}
'
{
  "success": true,
  "projectId": "proj_scenes_abc123xyz",
  "message": "Scenes project successfully created"
}
Try it out! Use the API playground on the right to test the Scenes endpoint directly.

Overview

Scenes allows you to create complex, multi-scene videos by combining different content types in a storyboard format. Each scene can be one of four types:
  • Avatar: A talking avatar scene with script and voice
  • Video: A video or image clip with optional voiceover
  • Picture in Picture: An avatar overlaid on a video/image background
  • Start/End Frame: AI-generated video transition between two images
This format is ideal for:
  • Long-form content with multiple segments
  • Tutorials with avatar explanations and demo clips
  • Marketing videos with varied visual styles
  • Storytelling with scene transitions
  • Educational content mixing talking heads and visuals
Scenes automatically handles transitions between different scene types and maintains consistent captions throughout the video.

Endpoint

POST /v1/project/create/scenes

Required Fields

scenes
array
required
Array of scene objects (1-50 scenes). Each scene defines a segment of your video.

Optional Fields

name
string
Video name (max 100 characters). If not provided, a name will be auto-generated from the scene scripts.
musicId
string
Background music ID from /v1/music/list.
caption
object
Caption settings for the video
aspectRatio
string
default:"ratio_9_16"
Video aspect ratio:
  • ratio_9_16: Vertical (TikTok, Reels, Shorts) - Recommended
  • ratio_16_9: Horizontal (YouTube)
  • ratio_1_1: Square (Instagram)
language
string
default:"en"
Language code for the video (2 characters). Example: en, es
webhook
string
HTTPS URL to receive completion notification (max 500 characters). Highly recommended for production use.
metadata
object
Custom metadata object (max 5KB). Store any additional data you need to associate with this video.
{
  "courseId": "course_123",
  "lessonNumber": 5
}

Scene Types

Avatar Scene

A talking avatar presents content with synchronized lip movements.
{
  "type": "avatar",
  "script": "Welcome to our tutorial! Today we'll learn about...",
  "avatarId": "professional_avatar_id",
  "voiceId": "confident_voice_id"
}
Required fields: script, avatarId, voiceId

Video Scene

A video or image clip plays, optionally with voiceover.
{
  "type": "video",
  "mediaId": "demo_video_id",
  "script": "As you can see in this demo...",
  "voiceId": "professional_voice_id"
}
Required fields: mediaId

Picture in Picture Scene

An avatar appears overlaid on a video/image background.
{
  "type": "picture_in_picture",
  "script": "As you can see in this demo...",
  "avatarId": "presenter_avatar_id",
  "voiceId": "professional_voice_id",
  "mediaId": "background_video_id"
}
Required fields: script, avatarId, voiceId, mediaId

Start/End Frame Scene

AI generates a video transition between two images.
{
  "type": "start_end_frame",
  "startFrameMediaId": "start_image_id",
  "endFrameMediaId": "end_image_id",
  "frameModel": "veo_3_1",
  "framePrompt": "Smooth camera zoom out revealing the full scene",
  "frameDuration": 5
}
Required fields: startFrameMediaId, endFrameMediaId, framePrompt

Request Examples

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({
    scenes: [
      {
        type: 'avatar',
        script: 'Welcome to our product demo! Let me show you how it works.',
        avatarId: 'professional_avatar_id',
        voiceId: 'confident_voice_id'
      },
      {
        type: 'video',
        mediaId: 'product_demo_video_id'
      },
      {
        type: 'avatar',
        script: 'As you can see, it is incredibly easy to use. Try it today!',
        avatarId: 'professional_avatar_id',
        voiceId: 'confident_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: 'avatar',
          script: 'Hi there! In this tutorial, I will walk you through the setup process step by step.',
          avatarId: 'friendly_avatar_id',
          voiceId: 'warm_voice_id'
        },
        {
          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'
        },
        {
          type: 'avatar',
          script: 'And that is it! You are all set up and ready to go.',
          avatarId: 'friendly_avatar_id',
          voiceId: 'warm_voice_id'
        }
      ],
      musicId: 'upbeat_background_id',
      aspectRatio: 'ratio_16_9',
      caption: {
        preset: 'modern',
        alignment: 'bottom',
        disabled: false
      },
      language: 'en',
      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({
      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'
        },
        {
          type: 'avatar',
          script: 'Incredible, right? This is the power of our solution.',
          avatarId: 'energetic_avatar_id',
          voiceId: 'excited_voice_id'
        }
      ],
      aspectRatio: 'ratio_9_16'
    })
  });

  return await response.json();
};

Response

{
  "success": true,
  "projectId": "proj_scenes_abc123xyz",
  "message": "Scenes project successfully created"
}

Webhook Notification

When your video is ready, we’ll POST to your webhook URL:
Webhook Payload
{
  "status": "COMPLETED",
  "data": {
    "videoId": "vid_scenes_abc123xyz",
    "status": "COMPLETED",
    "url": "https://cdn.tryhooked.ai/videos/abc123xyz.mp4",
    "shareUrl": "https://cdn.tryhooked.ai/shared/abc123xyz.mp4",
    "metadata": {
      "projectId": "proj_scenes_abc123xyz",
      "tutorialId": "getting-started"
    }
  },
  "message": "Video completed"
}
Your webhook endpoint must return a 200 status code. We’ll retry up to 3 times if the request fails.

Scene Type Requirements

Scene TypeRequired FieldsOptional Fields
avatarscript, avatarId, voiceId
videomediaIdscript, voiceId,
picture_in_picturescript, avatarId, voiceId, mediaId
start_end_framestartFrameMediaId, endFrameMediaId, framePromptframeModel, frameDuration

AI Models for Start/End Frame

ModelDescriptionBest For
kling_2_5Kling 2.5 modelFast generation, general transitions
veo_3_1Google Veo 3.1High quality, complex camera movements

Caption Presets

Available caption presets for the caption.preset field:
PresetDescription
defaultDefault caption style with bold text and shadow effects
beastBold uppercase style with Komika font
umiYellow glowing text style
tiktokViral & trendy style, perfect for social media
wrap1Wrapped style with red background highlight
wrap2Wrapped style with blue background highlight (uppercase)
arielBold uppercase style with purple highlight
hookedBrand style with purple background
classicClean, simple captions with black background
activeGreen background with bold text
bubbleWhite background bubble style
glassGlassmorphic transparency effect
comicComic Sans font with colorful style
glowPink and orange glow effects
pastelSoft pastel pink background
neonGreen neon glow effect
retroTVRetro TV style with cyan glow
redRed glow effect with white text
markerYellow marker/highlighter style
modernContemporary white background style
blueBlue background style
vividVibrant pink background with uppercase text

Best Practices

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 Start/End Frames

Leverage AI transitions for impressive visual effects between static images.

Error Handling

ErrorDescriptionSolution
At least one scene is requiredEmpty scenes arrayAdd at least one scene to the array
Cannot have more than 50 scenesToo many scenesReduce the number of scenes to 50 or fewer
Script is required for avatar scenesMissing script in avatar sceneAdd the script field
Avatar ID is required for avatar scenesMissing avatarIdAdd a valid avatarId from /v1/avatar/list
Voice ID is required for avatar scenesMissing voiceIdAdd a valid voiceId from /v1/voice/list
Media ID is required for video scenesMissing mediaId in video sceneAdd a valid mediaId
Not enough creditsInsufficient creditsTop up your account credits

Credits

Scenes videos use a credit model based on:
  • Base credits: Fixed cost per video
  • Avatar scene credits: Charged based on script duration (similar to UGC Video)
  • Video scenes: Included in base credits (no additional charge)
  • Start/End Frame: Additional credits for AI generation

Next Steps

Authorizations

x-api-key
string
header
required

Body

application/json
scenes
object[]
required

Array of scene objects (1-50 scenes)

Required array length: 1 - 50 elements
name
string

Video name (max 100 characters)

Maximum string length: 100
musicId
string

Background music ID from /v1/music/list

Maximum string length: 30
aspectRatio
enum<string>
default:ratio_9_16

Video aspect ratio

Available options:
ratio_9_16,
ratio_16_9,
ratio_1_1
caption
object
addStickers
boolean
default:false

Add AI-generated stickers to enhance video engagement

language
string
default:en

Language code (2 characters)

Required string length: 2
webhook
string

HTTPS URL to receive completion notification

Maximum string length: 500
metadata
object

Custom metadata object (max 5KB)

Response

Scenes project created successfully

success
boolean
projectId
string
message
string