Skip to main content
POST
/
v1
/
project
/
create
/
script-to-video
Create Script to Video
curl --request POST \
  --url https://5f6cf291bc31.ngrok-free.app/api/v1/project/create/script-to-video \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "script": "Artificial intelligence is transforming the way we work and live. From smart assistants to self-driving cars, AI is everywhere.",
  "voiceId": "confident_voice_id",
  "mediaType": "ai-images",
  "presetSettings": {
    "preset": "realistic",
    "quality": "pro"
  },
  "musicId": "2",
  "aspectRatio": "ratio_9_16",
  "caption": {
    "preset": "beast",
    "alignment": "bottom",
    "disabled": false
  },
  "addStickers": true,
  "audio": {
    "speed": 1,
    "stability": 0.5,
    "similarityBoost": 0.75,
    "style": 0,
    "useSpeakerBoost": true
  },
  "webhook": "https://yoursite.com/webhook",
  "metadata": {
    "contentType": "educational",
    "topic": "artificial-intelligence"
  }
}
'
{
  "success": true,
  "data": {
    "videoId": "vid_s2v_abc123xyz",
    "projectId": "proj_s2v_abc123xyz",
    "status": "STARTED"
  },
  "message": "Script to Video successfully created"
}
Try it out! Use the API playground on the right to test the Script to Video endpoint directly.

Overview

Script to Video transforms your written scripts into engaging videos with voice narration and auto-generated or custom media. This format is ideal for:
  • Educational content and tutorials
  • Social media content creation
  • Marketing videos
  • Storytelling and narrative content
  • News-style videos
Script to Video automatically generates visuals based on your script or allows you to provide custom media for full creative control.

Endpoint

POST /v1/project/create/script-to-video

Required Fields

script
string
required
The script for the video narration (1-10,000 characters). This will be converted to speech and synchronized with visuals.
voiceId
string
required
Voice ID from /v1/voice/list. The voice used for narrating the script.
mediaType
string
required
Type of media to generate:
  • ai-images: AI-generated images based on script
  • ai-videos: AI-generated video clips
  • media: Use stock media (requires media array)
  • gameplay: Use gameplay footage (requires gameplaySettings)

Optional Fields

name
string
Video name (max 100 characters)
presetSettings
object
Settings for auto-generated media (used when mediaType is ai-images or ai-videos)
media
array
Array of media IDs (max 50). The media must already be uploaded to your account. Required when mediaType is media. If not provided, media will be auto-generated based on mediaType.
gameplaySettings
object
Settings for gameplay footage (required when mediaType is gameplay)
musicId
string
Music ID from /v1/music/list for background music.
caption
object
Caption settings for the video
aspectRatio
string
default:"ratio_9_16"
Video aspect ratio:
  • ratio_9_16: Vertical (TikTok, Reels, Shorts)
  • ratio_16_9: Horizontal (YouTube)
  • ratio_1_1: Square (Instagram)
audio
object
Voice audio settings
addStickers
boolean
default:"false"
Enable automatic sticker generation for the video. Adds engaging visual elements automatically.
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.
{
  "campaignId": "summer2024",
  "contentType": "educational"
}

Request Examples

With AI-Generated Images

const response = await fetch('https://api.hooked.ai/v1/project/create/script-to-video', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.HOOKED_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    script: 'Artificial intelligence is transforming the way we work and live. From smart assistants to self-driving cars, AI is everywhere.',
    voiceId: 'confident_voice_id',
    mediaType: "ai-images",
    presetSettings: {
      preset: "realistic",
      quality: "pro"
    },
    musicId: "2",
    aspectRatio: 'ratio_9_16',
    caption: {
      preset: 'beast',
      alignment: 'bottom',
      disabled: false
    },
    addStickers: true,
    audio: {
      speed: 1,
      stability: 0.5,
      similarityBoost: 0.75,
      style: 0,
      useSpeakerBoost: true
    },
    webhook: 'https://yoursite.com/webhook',
    metadata: {
      contentType: 'educational',
      topic: 'artificial-intelligence'
    }
  })
});

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

With AI-Generated Videos

const createAIImageVideo = async () => {
  const response = await fetch('https://api.hooked.ai/v1/project/create/script-to-video', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.HOOKED_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'AI Technology Explainer',
      script: 'Artificial intelligence is transforming the way we work and live. From smart assistants to self-driving cars, AI is everywhere. Let\'s explore how this technology is shaping our future.',
      voiceId: 'confident_voice_id',
      mediaType: 'ai-videos',
      presetSettings: {
        preset: 'anime',
        quality: 'base'
      },
      musicId: 'music_ambient_01',
      aspectRatio: 'ratio_9_16',
      caption: {
        preset: 'modern',
        alignment: 'bottom',
        disabled: false
      },
      addStickers: true,
      audio: {
        speed: 1,
        stability: 0.5,
        similarityBoost: 0.75,
        style: 0,
        useSpeakerBoost: true
      },
      webhook: 'https://yoursite.com/webhook',
      metadata: {
        contentType: 'educational',
        topic: 'artificial-intelligence'
      }
    })
  });

  return await response.json();
};

With Custom Media

const createCustomMediaVideo = async () => {
  const response = await fetch('https://api.hooked.ai/v1/project/create/script-to-video', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.HOOKED_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Product Showcase',
      script: 'Introducing our revolutionary new product. It\'s designed to make your life easier and more productive. Watch as we demonstrate its incredible features.',
      voiceId: 'enthusiastic_voice_id',
      media: ['intro_shot', 'demo_shot', 'feature_image'],
      musicId: 'music_upbeat_01',
      aspectRatio: 'ratio_9_16',
      caption: {
        preset: 'wrap1',
        alignment: 'bottom',
        disabled: false
      },
      mediaType: 'media',
      addStickers: true,
      audio: {
        speed: 1,
        stability: 0.5,
        similarityBoost: 0.75,
        style: 0,
        useSpeakerBoost: true
      },
      webhook: 'https://yoursite.com/webhook',
      metadata: {
        contentType: 'educational',
        topic: 'artificial-intelligence'
      }
    })
  });

  return await response.json();
};

With Gameplay

const createGamingVideo = async () => {
  const response = await fetch('https://api.hooked.ai/v1/project/create/script-to-video', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.HOOKED_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Gaming Tips Video',
      script: 'Want to level up your gaming skills? Here are three pro tips that will help you dominate your opponents. Tip one: always check your surroundings...',
      voiceId: 'energetic_voice_id',
      mediaType: 'gameplay',
      gameplaySettings: {
        selectedGame: 'minecraft',
        selectedVideo: 'minecraft-1'
      },
      musicId: 'music_upbeat_01',
      aspectRatio: 'ratio_9_16',
      caption: {
        preset: 'beast',
        alignment: 'top',
        disabled: false
      },
      addStickers: true,
      audio: {
        speed: 1,
        stability: 0.5,
        similarityBoost: 0.75,
        style: 0,
        useSpeakerBoost: true
      },
      webhook: 'https://yoursite.com/webhook',
      metadata: {
        contentType: 'educational',
        topic: 'artificial-intelligence'
      }
    })
  });

  return await response.json();
};

Response

{
  "success": true,
  "data": {
    "videoId": "vid_s2v_abc123xyz",
    "projectId": "proj_s2v_abc123xyz",
    "status": "STARTED"
  },
  "message": "Script to Video successfully created"
}

Webhook Notification

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

Visual Style Presets

Available visual style presets for the presetSettings.preset field:
PresetDescription
realisticPure photorealistic style with natural lighting and lifelike details
animeClassic anime style with large expressive eyes, vibrant colors, clean line art
cinematicHollywood movie cinematography with dramatic lighting and wide shots
fantasyEpic fantasy art with magical elements, mythical creatures, enchanted environments
cyberpunk-animeFuturistic anime style with neon colors, cybernetic elements, dystopian atmosphere
pixar3D animated style inspired by Pixar with smooth rendering and expressive characters
comic-bookAmerican comic book style with bold colors, dynamic action, superhero aesthetics
real-animeRealistic anime style blending photorealistic elements with anime aesthetics
ghibli-studioStudio Ghibli animation style with soft colors, whimsical characters, magical atmosphere
sketch-black-and-whiteMonochrome pencil sketch with detailed shading and artistic line work
art-styleFine art style with painterly techniques, artistic composition, classical aesthetics
retro-anime1980s-90s anime aesthetic with vintage color palette and classic animation style
80s-fantasy-movieRetro 80s fantasy film aesthetic with practical effects, vibrant colors
cartoonClassic cartoon style with bold outlines, flat colors, exaggerated features
creativeAbstract creative style with experimental techniques and innovative artistic approaches
gta-vGrand Theft Auto V video game style with urban aesthetic and satirical tone
sketch-colorColored sketch with vibrant markers and artistic illustration techniques
japanese-inkTraditional Japanese sumi-e ink painting with black ink, red accents, flowing brushstrokes
space-marines-40kWarhammer 40K Space Marines style with power armor, gothic architecture, grimdark atmosphere
haunted-lineworkGothic horror style with intricate linework, dark atmosphere, supernatural elements
ink-styleModern ink art with dynamic strokes, abstract elements, energetic composition
neon-futuristicCyberpunk aesthetic with bright neon colors, futuristic technology, sci-fi atmosphere
minecraftBlocky pixel art style inspired by Minecraft with cubic shapes and vibrant colors
pixel-art8-bit and 16-bit pixel art style with retro gaming aesthetics and limited color palette
collageMixed media collage with newspaper elements, geometric shapes, layered textures
legoLEGO brick style with plastic toy aesthetic and modular construction elements
technical-blueprintsEngineering blueprint style with technical drawings, measurements, schematic details

Media Types

Available media types for mediaType:
TypeDescription
ai-imagesAI-generated images based on your script content
ai-videosAI-generated video clips synchronized with narration
mediaStock media automatically selected based on script
gameplayGameplay footage from popular games

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

Write Clear Scripts

Structure your script with clear sentences and natural pauses for better pacing.

Choose the Right Media Type

Use ai-images for educational content, gameplay for gaming, custom media for brands.

Match Voice to Content

Choose a voice that fits your content tone - energetic for gaming, professional for business.

Use Webhooks

Always use webhooks in production instead of polling for video status.

Error Handling

ErrorDescriptionSolution
script: Script is requiredMissing or empty scriptAdd the script field with your content
voiceId: Voice not foundInvalid voice IDUse a valid voice ID from /v1/voice/list
presetSettings.preset: Preset is requiredMissing preset when using auto-generated mediaAdd the preset field in presetSettings
webhook: Must be a valid HTTPS URLInvalid webhook URLEnsure webhook URL starts with https://
media: Cannot have more than 50 media itemsToo many media itemsReduce media array to 50 items or fewer
Not enough creditsInsufficient creditsTop up your account credits

Next Steps

Authorizations

x-api-key
string
header
required

Body

application/json
script
string
required

The script for the video narration (1-10,000 characters)

Required string length: 1 - 10000
voiceId
string
required

Voice ID from /v1/voice/list

Maximum string length: 30
mediaType
enum<string>
default:ai-images
required

Type of media to generate

Available options:
ai-images,
ai-videos,
media,
gameplay
name
string

Video name (max 100 characters)

Maximum string length: 100
musicId
string

Music ID from /v1/music/list for background music

Maximum string length: 30
media
string[]

Array of media IDs (max 50). The media must already be uploaded to your account. Required when mediaType is 'media'. If not provided, media will be auto-generated.

Maximum array length: 50

Media ID

presetSettings
object

Settings for auto-generated media (used when mediaType is 'ai-images' or 'ai-videos')

gameplaySettings
object

Settings for gameplay footage (used when mediaType is 'gameplay')

caption
object
audio
object

Voice audio settings

addStickers
boolean
default:false

Enable automatic sticker generation for the video

aspectRatio
enum<string>
default:ratio_9_16

Video aspect ratio

Available options:
ratio_9_16,
ratio_16_9,
ratio_1_1
webhook
string

HTTPS URL to receive completion notification

Maximum string length: 500
metadata
object

Custom metadata object (max 5KB)

Response

Script to Video created successfully

success
boolean
data
object
message
string