> ## 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.
# Script to Video
> Create videos from scripts with AI-generated or custom media
**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
The script for the video narration (1-10,000 characters). This will be converted to speech and synchronized with visuals.
Voice ID from `/v1/voice/list`. The voice used for narrating the script.
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
Video name (max 100 characters)
Settings for auto-generated media (used when `mediaType` is `ai-images` or `ai-videos`)
Visual style preset for AI-generated images/videos. Available presets: `realistic`, `anime`, `cinematic`, `fantasy`, `cyberpunk-anime`, `pixar`, `comic-book`, `real-anime`, `ghibli-studio`, `sketch-black-and-white`, `art-style`, `retro-anime`, `80s-fantasy-movie`, `cartoon`, `creative`, `gta-v`, `sketch-color`, `japanese-ink`, `space-marines-40k`, `haunted-linework`, `ink-style`, `neon-futuristic`, `minecraft`, `pixel-art`, `collage`, `lego`, `technical-blueprints`
Generation quality: `base`, `pro`, or `ultra`
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`.
Settings for gameplay footage (required when `mediaType` is `gameplay`)
Game identifier for gameplay footage. Available games: `minecraft`, `subway-s`, `temple-run`, `gta`
Specific gameplay video to use. Available videos:
* Minecraft: `minecraft-1` through `minecraft-8`
* Subway S: `subway-s-1` through `subway-s-11`
* Temple Run: `temple-run-1` through `temple-run-8`
* GTA: `gta-1` through `gta-12`
Music ID from `/v1/music/list` for background music.
Caption settings for the video
Caption preset style. Available presets: `default`, `beast`, `umi`, `tiktok`, `wrap1`, `wrap2`, `ariel`, `hooked`, `classic`, `active`, `bubble`, `glass`, `comic`, `glow`, `pastel`, `neon`, `retroTV`, `red`, `marker`, `modern`, `blue`, `vivid`.
Caption position on the video: `top`, `middle`, or `bottom`
Set to `true` to hide captions on the video
Video aspect ratio:
* `ratio_9_16`: Vertical (TikTok, Reels, Shorts)
* `ratio_16_9`: Horizontal (YouTube)
* `ratio_1_1`: Square (Instagram)
Voice audio settings
Voice speed multiplier (0.7 to 1.2)
Voice stability (0 to 1). Higher values produce more consistent speech.
Voice similarity boost (0 to 1). Higher values make the voice more similar to the original.
Voice style exaggeration (0 to 1).
Enable speaker boost for clearer audio.
Enable automatic sticker generation for the video. Adds engaging visual elements automatically.
HTTPS URL to receive completion notification (max 500 characters). **Highly recommended** for production use.
Custom metadata object (max 5KB). Store any additional data you need to associate with this video.
```json theme={null}
{
"campaignId": "summer2024",
"contentType": "educational"
}
```
***
## Request Examples
## With AI-Generated Images
```javascript theme={null}
const response = await fetch('https://api.hooked.so/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
```javascript theme={null}
const createAIImageVideo = async () => {
const response = await fetch('https://api.hooked.so/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
```javascript theme={null}
const createCustomMediaVideo = async () => {
const response = await fetch('https://api.hooked.so/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
```javascript theme={null}
const createGamingVideo = async () => {
const response = await fetch('https://api.hooked.so/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
```json Success Response theme={null}
{
"success": true,
"data": {
"videoId": "vid_s2v_abc123xyz",
"projectId": "proj_s2v_abc123xyz",
"status": "STARTED"
},
"message": "Script to Video successfully created"
}
```
```json Error Response - Validation Error theme={null}
{
"success": false,
"message": "script: Script is required"
}
```
```json Error Response - Voice Not Found theme={null}
{
"success": false,
"message": "voiceId: Voice not found"
}
```
***
## Webhook Notification
When your video is ready, we'll POST to your webhook URL:
```json Webhook Payload theme={null}
{
"status": "COMPLETED",
"data": {
"videoId": "vid_s2v_abc123xyz",
"status": "COMPLETED",
"url": "https://cdn.hooked.so/videos/abc123xyz.mp4",
"shareUrl": "https://cdn.hooked.so/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:
| Preset | Description |
| ------------------------ | -------------------------------------------------------------------------------------------- |
| `realistic` | Pure photorealistic style with natural lighting and lifelike details |
| `anime` | Classic anime style with large expressive eyes, vibrant colors, clean line art |
| `cinematic` | Hollywood movie cinematography with dramatic lighting and wide shots |
| `fantasy` | Epic fantasy art with magical elements, mythical creatures, enchanted environments |
| `cyberpunk-anime` | Futuristic anime style with neon colors, cybernetic elements, dystopian atmosphere |
| `pixar` | 3D animated style inspired by Pixar with smooth rendering and expressive characters |
| `comic-book` | American comic book style with bold colors, dynamic action, superhero aesthetics |
| `real-anime` | Realistic anime style blending photorealistic elements with anime aesthetics |
| `ghibli-studio` | Studio Ghibli animation style with soft colors, whimsical characters, magical atmosphere |
| `sketch-black-and-white` | Monochrome pencil sketch with detailed shading and artistic line work |
| `art-style` | Fine art style with painterly techniques, artistic composition, classical aesthetics |
| `retro-anime` | 1980s-90s anime aesthetic with vintage color palette and classic animation style |
| `80s-fantasy-movie` | Retro 80s fantasy film aesthetic with practical effects, vibrant colors |
| `cartoon` | Classic cartoon style with bold outlines, flat colors, exaggerated features |
| `creative` | Abstract creative style with experimental techniques and innovative artistic approaches |
| `gta-v` | Grand Theft Auto V video game style with urban aesthetic and satirical tone |
| `sketch-color` | Colored sketch with vibrant markers and artistic illustration techniques |
| `japanese-ink` | Traditional Japanese sumi-e ink painting with black ink, red accents, flowing brushstrokes |
| `space-marines-40k` | Warhammer 40K Space Marines style with power armor, gothic architecture, grimdark atmosphere |
| `haunted-linework` | Gothic horror style with intricate linework, dark atmosphere, supernatural elements |
| `ink-style` | Modern ink art with dynamic strokes, abstract elements, energetic composition |
| `neon-futuristic` | Cyberpunk aesthetic with bright neon colors, futuristic technology, sci-fi atmosphere |
| `minecraft` | Blocky pixel art style inspired by Minecraft with cubic shapes and vibrant colors |
| `pixel-art` | 8-bit and 16-bit pixel art style with retro gaming aesthetics and limited color palette |
| `collage` | Mixed media collage with newspaper elements, geometric shapes, layered textures |
| `lego` | LEGO brick style with plastic toy aesthetic and modular construction elements |
| `technical-blueprints` | Engineering blueprint style with technical drawings, measurements, schematic details |
***
## Media Types
Available media types for `mediaType`:
| Type | Description |
| ----------- | ---------------------------------------------------- |
| `ai-images` | AI-generated images based on your script content |
| `ai-videos` | AI-generated video clips synchronized with narration |
| `media` | Stock media automatically selected based on script |
| `gameplay` | Gameplay footage from popular games |
***
## Caption Presets
Available caption presets for the `caption.preset` field:
| Preset | Description |
| --------- | -------------------------------------------------------- |
| `default` | Default caption style with bold text and shadow effects |
| `beast` | Bold uppercase style with Komika font |
| `umi` | Yellow glowing text style |
| `tiktok` | Viral & trendy style, perfect for social media |
| `wrap1` | Wrapped style with red background highlight |
| `wrap2` | Wrapped style with blue background highlight (uppercase) |
| `ariel` | Bold uppercase style with purple highlight |
| `hooked` | Brand style with purple background |
| `classic` | Clean, simple captions with black background |
| `active` | Green background with bold text |
| `bubble` | White background bubble style |
| `glass` | Glassmorphic transparency effect |
| `comic` | Comic Sans font with colorful style |
| `glow` | Pink and orange glow effects |
| `pastel` | Soft pastel pink background |
| `neon` | Green neon glow effect |
| `retroTV` | Retro TV style with cyan glow |
| `red` | Red glow effect with white text |
| `marker` | Yellow marker/highlighter style |
| `modern` | Contemporary white background style |
| `blue` | Blue background style |
| `vivid` | Vibrant pink background with uppercase text |
***
## Best Practices
Structure your script with clear sentences and natural pauses for better pacing.
Use ai-images for educational content, gameplay for gaming, custom media for brands.
Choose a voice that fits your content tone - energetic for gaming, professional for business.
Always use webhooks in production instead of polling for video status.
***
## Error Handling
| Error | Description | Solution |
| --------------------------------------------- | ---------------------------------------------- | ------------------------------------------ |
| `script: Script is required` | Missing or empty script | Add the `script` field with your content |
| `voiceId: Voice not found` | Invalid voice ID | Use a valid voice ID from `/v1/voice/list` |
| `presetSettings.preset: Preset is required` | Missing preset when using auto-generated media | Add the `preset` field in `presetSettings` |
| `webhook: Must be a valid HTTPS URL` | Invalid webhook URL | Ensure webhook URL starts with `https://` |
| `media: Cannot have more than 50 media items` | Too many media items | Reduce media array to 50 items or fewer |
| `Not enough credits` | Insufficient credits | Top up your account credits |
***
## Next Steps
Find the perfect voice for your video
Add background music to your videos
View all your created videos
Learn how to handle webhook notifications
## OpenAPI
````yaml POST /v1/project/create/script-to-video
openapi: 3.0.0
info:
title: Hooked API
version: 1.0.0
description: AI Video Generation API
servers:
- url: https://api.hooked.so
security:
- ApiKeyAuth: []
paths:
/v1/project/create/script-to-video:
post:
tags:
- Videos
summary: Create Script to Video
description: Create videos from scripts with AI-generated or custom media
operationId: createScriptToVideo
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- script
- voiceId
- mediaType
properties:
script:
type: string
description: The script for the video narration (1-10,000 characters)
minLength: 1
maxLength: 10000
name:
type: string
description: Video name (max 100 characters)
maxLength: 100
voiceId:
type: string
description: Voice ID from /v1/voice/list
maxLength: 30
mediaType:
type: string
enum:
- ai-images
- ai-videos
- media
- gameplay
description: Type of media to generate
default: ai-images
musicId:
type: string
description: Music ID from /v1/music/list for background music
maxLength: 30
media:
type: array
description: >-
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.
maxItems: 50
items:
type: string
description: Media ID
presetSettings:
type: object
description: >-
Settings for auto-generated media (used when mediaType is
'ai-images' or 'ai-videos')
properties:
preset:
type: string
enum:
- realistic
- anime
- cinematic
- fantasy
- cyberpunk-anime
- pixar
- comic-book
- real-anime
- ghibli-studio
- sketch-black-and-white
- art-style
- retro-anime
- 80s-fantasy-movie
- cartoon
- creative
- gta-v
- sketch-color
- japanese-ink
- space-marines-40k
- haunted-linework
- ink-style
- neon-futuristic
- minecraft
- pixel-art
- collage
- lego
- technical-blueprints
description: Visual style preset for AI-generated images/videos
default: realistic
quality:
type: string
enum:
- base
- pro
- ultra
description: Generation quality
default: base
gameplaySettings:
type: object
description: >-
Settings for gameplay footage (used when mediaType is
'gameplay')
properties:
selectedGame:
type: string
enum:
- minecraft
- subway-s
- temple-run
- gta
description: Game identifier for gameplay footage
default: minecraft
selectedVideo:
type: string
enum:
- minecraft-1
- minecraft-2
- minecraft-3
- minecraft-4
- minecraft-5
- minecraft-6
- minecraft-7
- minecraft-8
- subway-s-1
- subway-s-2
- subway-s-3
- subway-s-4
- subway-s-5
- subway-s-6
- subway-s-7
- subway-s-8
- subway-s-9
- subway-s-10
- subway-s-11
- temple-run-1
- temple-run-2
- temple-run-3
- temple-run-4
- temple-run-5
- temple-run-6
- temple-run-7
- temple-run-8
- gta-1
- gta-2
- gta-3
- gta-4
- gta-5
- gta-6
- gta-7
- gta-8
- gta-9
- gta-10
- gta-11
- gta-12
description: Specific gameplay video to use
default: minecraft-1
caption:
type: object
properties:
preset:
type: string
enum:
- default
- beast
- umi
- tiktok
- wrap1
- wrap2
- ariel
- hooked
- classic
- active
- bubble
- glass
- comic
- glow
- pastel
- neon
- retroTV
- red
- marker
- modern
- blue
- vivid
description: Caption preset style
default: wrap1
alignment:
type: string
enum:
- top
- middle
- bottom
description: Caption position on video
default: bottom
disabled:
type: boolean
description: Set to false to show captions on the video
default: false
audio:
type: object
description: Voice audio settings
properties:
speed:
type: number
description: Voice speed multiplier (0.7 to 1.2)
minimum: 0.7
maximum: 1.2
default: 1
stability:
type: number
description: Voice stability (0 to 1)
minimum: 0
maximum: 1
default: 0.5
similarityBoost:
type: number
description: Voice similarity boost (0 to 1)
minimum: 0
maximum: 1
default: 0.75
style:
type: number
description: Voice style exaggeration (0 to 1)
minimum: 0
maximum: 1
default: 0
useSpeakerBoost:
type: boolean
description: Enable speaker boost for clearer audio
default: true
addStickers:
type: boolean
description: Enable automatic sticker generation for the video
default: false
aspectRatio:
type: string
enum:
- ratio_9_16
- ratio_16_9
- ratio_1_1
description: Video aspect ratio
default: ratio_9_16
webhook:
type: string
description: HTTPS URL to receive completion notification
maxLength: 500
metadata:
type: object
description: Custom metadata object (max 5KB)
example:
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
responses:
'200':
description: Script to Video created successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
data:
type: object
properties:
videoId:
type: string
projectId:
type: string
status:
type: string
message:
type: string
example:
success: true
data:
videoId: vid_s2v_abc123xyz
projectId: proj_s2v_abc123xyz
status: STARTED
message: Script to Video successfully created
'400':
description: Validation error
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
example:
success: false
message: 'script: Script is required'
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
example:
success: false
message: Invalid API key
security:
- ApiKeyAuth: []
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
````