Script to Video

Create Script to Video

curl --request POST \
  --url https://api.hooked.so/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"
  }
}
'

import requests

url = "https://api.hooked.so/v1/project/create/script-to-video"

payload = {
    "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"
    }
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<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'}
  })
};

fetch('https://api.hooked.so/v1/project/create/script-to-video', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.hooked.so/v1/project/create/script-to-video",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.hooked.so/v1/project/create/script-to-video"

	payload := strings.NewReader("{\n  \"script\": \"Artificial intelligence is transforming the way we work and live. From smart assistants to self-driving cars, AI is everywhere.\",\n  \"voiceId\": \"confident_voice_id\",\n  \"mediaType\": \"ai-images\",\n  \"presetSettings\": {\n    \"preset\": \"realistic\",\n    \"quality\": \"pro\"\n  },\n  \"musicId\": \"2\",\n  \"aspectRatio\": \"ratio_9_16\",\n  \"caption\": {\n    \"preset\": \"beast\",\n    \"alignment\": \"bottom\",\n    \"disabled\": false\n  },\n  \"addStickers\": true,\n  \"audio\": {\n    \"speed\": 1,\n    \"stability\": 0.5,\n    \"similarityBoost\": 0.75,\n    \"style\": 0,\n    \"useSpeakerBoost\": true\n  },\n  \"webhook\": \"https://yoursite.com/webhook\",\n  \"metadata\": {\n    \"contentType\": \"educational\",\n    \"topic\": \"artificial-intelligence\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.hooked.so/v1/project/create/script-to-video")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"script\": \"Artificial intelligence is transforming the way we work and live. From smart assistants to self-driving cars, AI is everywhere.\",\n  \"voiceId\": \"confident_voice_id\",\n  \"mediaType\": \"ai-images\",\n  \"presetSettings\": {\n    \"preset\": \"realistic\",\n    \"quality\": \"pro\"\n  },\n  \"musicId\": \"2\",\n  \"aspectRatio\": \"ratio_9_16\",\n  \"caption\": {\n    \"preset\": \"beast\",\n    \"alignment\": \"bottom\",\n    \"disabled\": false\n  },\n  \"addStickers\": true,\n  \"audio\": {\n    \"speed\": 1,\n    \"stability\": 0.5,\n    \"similarityBoost\": 0.75,\n    \"style\": 0,\n    \"useSpeakerBoost\": true\n  },\n  \"webhook\": \"https://yoursite.com/webhook\",\n  \"metadata\": {\n    \"contentType\": \"educational\",\n    \"topic\": \"artificial-intelligence\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.hooked.so/v1/project/create/script-to-video")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"script\": \"Artificial intelligence is transforming the way we work and live. From smart assistants to self-driving cars, AI is everywhere.\",\n  \"voiceId\": \"confident_voice_id\",\n  \"mediaType\": \"ai-images\",\n  \"presetSettings\": {\n    \"preset\": \"realistic\",\n    \"quality\": \"pro\"\n  },\n  \"musicId\": \"2\",\n  \"aspectRatio\": \"ratio_9_16\",\n  \"caption\": {\n    \"preset\": \"beast\",\n    \"alignment\": \"bottom\",\n    \"disabled\": false\n  },\n  \"addStickers\": true,\n  \"audio\": {\n    \"speed\": 1,\n    \"stability\": 0.5,\n    \"similarityBoost\": 0.75,\n    \"style\": 0,\n    \"useSpeakerBoost\": true\n  },\n  \"webhook\": \"https://yoursite.com/webhook\",\n  \"metadata\": {\n    \"contentType\": \"educational\",\n    \"topic\": \"artificial-intelligence\"\n  }\n}"

response = http.request(request)
puts response.read_body

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

{
  "success": false,
  "message": "script: Script is required"
}

{
  "success": false,
  "message": "voiceId: Voice not found"
}

POST

project

create

script-to-video

Create Script to Video

curl --request POST \
  --url https://api.hooked.so/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"
  }
}
'

import requests

url = "https://api.hooked.so/v1/project/create/script-to-video"

payload = {
    "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"
    }
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<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'}
  })
};

fetch('https://api.hooked.so/v1/project/create/script-to-video', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.hooked.so/v1/project/create/script-to-video",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.hooked.so/v1/project/create/script-to-video"

	payload := strings.NewReader("{\n  \"script\": \"Artificial intelligence is transforming the way we work and live. From smart assistants to self-driving cars, AI is everywhere.\",\n  \"voiceId\": \"confident_voice_id\",\n  \"mediaType\": \"ai-images\",\n  \"presetSettings\": {\n    \"preset\": \"realistic\",\n    \"quality\": \"pro\"\n  },\n  \"musicId\": \"2\",\n  \"aspectRatio\": \"ratio_9_16\",\n  \"caption\": {\n    \"preset\": \"beast\",\n    \"alignment\": \"bottom\",\n    \"disabled\": false\n  },\n  \"addStickers\": true,\n  \"audio\": {\n    \"speed\": 1,\n    \"stability\": 0.5,\n    \"similarityBoost\": 0.75,\n    \"style\": 0,\n    \"useSpeakerBoost\": true\n  },\n  \"webhook\": \"https://yoursite.com/webhook\",\n  \"metadata\": {\n    \"contentType\": \"educational\",\n    \"topic\": \"artificial-intelligence\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.hooked.so/v1/project/create/script-to-video")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"script\": \"Artificial intelligence is transforming the way we work and live. From smart assistants to self-driving cars, AI is everywhere.\",\n  \"voiceId\": \"confident_voice_id\",\n  \"mediaType\": \"ai-images\",\n  \"presetSettings\": {\n    \"preset\": \"realistic\",\n    \"quality\": \"pro\"\n  },\n  \"musicId\": \"2\",\n  \"aspectRatio\": \"ratio_9_16\",\n  \"caption\": {\n    \"preset\": \"beast\",\n    \"alignment\": \"bottom\",\n    \"disabled\": false\n  },\n  \"addStickers\": true,\n  \"audio\": {\n    \"speed\": 1,\n    \"stability\": 0.5,\n    \"similarityBoost\": 0.75,\n    \"style\": 0,\n    \"useSpeakerBoost\": true\n  },\n  \"webhook\": \"https://yoursite.com/webhook\",\n  \"metadata\": {\n    \"contentType\": \"educational\",\n    \"topic\": \"artificial-intelligence\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.hooked.so/v1/project/create/script-to-video")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"script\": \"Artificial intelligence is transforming the way we work and live. From smart assistants to self-driving cars, AI is everywhere.\",\n  \"voiceId\": \"confident_voice_id\",\n  \"mediaType\": \"ai-images\",\n  \"presetSettings\": {\n    \"preset\": \"realistic\",\n    \"quality\": \"pro\"\n  },\n  \"musicId\": \"2\",\n  \"aspectRatio\": \"ratio_9_16\",\n  \"caption\": {\n    \"preset\": \"beast\",\n    \"alignment\": \"bottom\",\n    \"disabled\": false\n  },\n  \"addStickers\": true,\n  \"audio\": {\n    \"speed\": 1,\n    \"stability\": 0.5,\n    \"similarityBoost\": 0.75,\n    \"style\": 0,\n    \"useSpeakerBoost\": true\n  },\n  \"webhook\": \"https://yoursite.com/webhook\",\n  \"metadata\": {\n    \"contentType\": \"educational\",\n    \"topic\": \"artificial-intelligence\"\n  }\n}"

response = http.request(request)
puts response.read_body

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

{
  "success": false,
  "message": "script: Script is required"
}

{
  "success": false,
  "message": "voiceId: Voice not found"
}

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)

Show Preset Settings Object

preset

string

default:"realistic"

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

quality

string

default:"base"

Generation quality: base, pro, or ultra

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)

Show Gameplay Settings Object

selectedGame

string

default:"minecraft"

Game identifier for gameplay footage. Available games: minecraft, subway-s, temple-run, gta

selectedVideo

string

default:"minecraft-1"

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

musicId

string

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

caption

object

Caption settings for the video

Show Caption Object

preset

string

default:"wrap1"

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.

alignment

string

default:"bottom"

Caption position on the video: top, middle, or bottom

disabled

boolean

default:"false"

Set to true to hide captions on 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

Show Audio Settings Object

speed

number

default:"1"

Voice speed multiplier (0.7 to 1.2)

stability

number

default:"0.5"

Voice stability (0 to 1). Higher values produce more consistent speech.

similarityBoost

number

default:"0.75"

Voice similarity boost (0 to 1). Higher values make the voice more similar to the original.

style

number

default:"0"

Voice style exaggeration (0 to 1).

useSpeakerBoost

boolean

default:"true"

Enable speaker boost for clearer audio.

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.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

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

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

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

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

{
  "success": false,
  "message": "script: Script is required"
}

{
  "success": false,
  "message": "voiceId: Voice not found"
}

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.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

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

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

List Voices

Find the perfect voice for your video

List Music

Add background music to your videos

List Videos

View all your created videos

Webhooks Guide

Learn how to handle webhook notifications

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')

Show child attributes

gameplaySettings

object

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

Show child attributes

caption

object

Show child attributes

audio

object

Voice audio settings

Show child attributes

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

Show child attributes

message

string

Scenes Talking Avatar

Getting Started

Resources

Videos

Templates

Trends

Niches

Social Accounts

Social Search

Scheduling

Overview

Endpoint

Required Fields

Optional Fields

Request Examples

With AI-Generated Images

With AI-Generated Videos

With Custom Media

With Gameplay

Response

Webhook Notification

Visual Style Presets

Media Types

Caption Presets

Best Practices

Write Clear Scripts

Choose the Right Media Type

Match Voice to Content

Use Webhooks

Error Handling

Next Steps

List Voices

List Music

List Videos

Webhooks Guide

Authorizations

Body

Response

​Overview

​Endpoint

​Required Fields

​Optional Fields

​Request Examples

​With AI-Generated Images

​With AI-Generated Videos

​With Custom Media

​With Gameplay

​Response

​Webhook Notification

​Visual Style Presets

​Media Types

​Caption Presets

​Best Practices

Write Clear Scripts

Choose the Right Media Type

Match Voice to Content

Use Webhooks

​Error Handling

​Next Steps

List Voices

List Music

List Videos

Webhooks Guide

Authorizations

Body

Response

Overview

Endpoint

Required Fields

Optional Fields

Request Examples

With AI-Generated Images

With AI-Generated Videos

With Custom Media

With Gameplay

Response

Webhook Notification

Visual Style Presets

Media Types

Caption Presets

Best Practices

Error Handling

Next Steps