Prompt to Video

Try it out! Use the API playground on the right to test the Prompt to Video endpoint directly.

Overview

Prompt to Video transforms your text prompts into engaging videos with AI-generated scripts, voice narration and auto-generated or custom media. This format is ideal for:

Quick content creation without writing scripts
Educational content and tutorials
Social media content creation
Marketing videos
Storytelling and narrative content

Prompt to Video automatically generates a script from your prompt, then creates visuals based on that script. You can also provide custom media for full creative control.

Endpoint

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

Required Fields

prompt

string

required

Describe the video you want to create (1-4000 characters). The AI will generate a professional script from this prompt.Example: “Create an engaging video about the top 5 productivity tips for remote workers”

targetDuration

number

default:60

required

Target duration for the generated video in seconds

Minimum: 10 seconds
Maximum: 120 seconds
Default: 60 seconds

voiceId

string

required

Voice ID from /v1/voice/list. The voice used for narrating the generated script.

presetSettings

object

required

Settings for auto-generated media (used when media is not provided)

Show Preset Settings Object

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
gameplay: Use gameplay footage

preset

string

required

Visual style preset (max 100 characters). Examples: cinematic, anime, realistic, cartoon

quality

string

default:"base"

required

Generation quality: base, pro, or ultra

caption

object

required

Caption settings for the video

Show Caption Object

preset

string

required

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

required

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

disabled

boolean

default:"false"

required

Set to true to hide captions on the video

aspectRatio

string

default:"ratio_9_16"

required

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"

required

Language code for the video (2 characters). Example: en, es

addStickers

boolean

default:"false"

required

Enable automatic sticker generation for the video. Adds engaging visual elements automatically.

Optional Fields

name

string

Video name (max 100 characters). If not provided, a name will be auto-generated from your prompt.

musicId

string

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

media

array

Custom media items (max 50). If not provided, media will be auto-generated based on presetSettings.

Show Media Object

string

required

Unique media ID (max 30 characters)

type

string

required

Media type: video or image

url

string

required

Public URL to the media file. Must be HTTPS.

title

string

Optional title/name for the media

durationInFrames

number

Duration in frames (25 frames = 1 second at 25fps)

isAIGenerated

boolean

default:"false"

Flag to indicate if media was AI-generated

gameplaySettings

object

Settings for gameplay footage (when presetSettings.mediaType is gameplay)

Show Gameplay Settings Object

selectedGame

string

required

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

selectedVideo

string

required

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

audio

object

Voice audio settings

Show Audio Settings Object

speed

number

default:"1"

Voice speed multiplier (0.5 to 2.0)

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.

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.tryhooked.ai/v1/project/create/prompt-to-video', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.HOOKED_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    prompt: 'Create an engaging video about the top 5 productivity tips for remote workers. Include practical advice and make it motivational.',
    voiceId: 'confident_voice_id',
    targetDuration: 60,
    presetSettings: {
      mediaType: "ai-images",
      preset: "realistic",
      quality: "pro"
    },
    musicId: "2",
    aspectRatio: 'ratio_9_16',
    caption: {
      preset: 'beast',
      alignment: 'bottom',
      disabled: false
    },
    language: 'en',
    addStickers: true,
    audio: {
      speed: 1,
      stability: 0.5,
      similarityBoost: 0.75,
      style: 0,
      useSpeakerBoost: true
    },
    webhook: 'https://yoursite.com/webhook',
    metadata: {
      contentType: 'educational',
      topic: 'productivity'
    }
  })
});

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

With AI-Generated Videos

const createAIVideoFromPrompt = async () => {
  const response = await fetch('https://api.tryhooked.ai/v1/project/create/prompt-to-video', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.HOOKED_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'AI Technology Explainer',
      prompt: 'Explain how artificial intelligence is transforming the way we work and live. Cover smart assistants, self-driving cars, and future applications.',
      voiceId: 'confident_voice_id',
      targetDuration: 60,
      presetSettings: {
        mediaType: 'ai-videos',
        preset: 'anime',
        quality: 'base'
      },
      musicId: 'music_ambient_01',
      aspectRatio: 'ratio_9_16',
      caption: {
        preset: 'modern',
        alignment: 'bottom',
        disabled: false
      },
      language: 'en',
      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.tryhooked.ai/v1/project/create/prompt-to-video', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.HOOKED_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Product Showcase',
      prompt: 'Create a compelling product introduction video. Highlight the revolutionary features that make life easier and more productive.',
      voiceId: 'enthusiastic_voice_id',
      targetDuration: 45,
      media: [
        {
          id: 'intro_shot',
          type: 'video',
          title: 'Product Intro',
          url: 'https://your-cdn.com/intro.mp4',
          durationInFrames: 150,
          isAIGenerated: true
        },
        {
          id: 'demo_shot',
          type: 'video',
          title: 'Product Demo',
          url: 'https://your-cdn.com/demo.mp4',
          durationInFrames: 200,
          isAIGenerated: false
        },
        {
          id: 'feature_image',
          type: 'image',
          title: 'Feature Highlight',
          url: 'https://your-cdn.com/feature.jpg',
          durationInFrames: 75,
          isAIGenerated: false
        }
      ],
      musicId: 'music_upbeat_01',
      aspectRatio: 'ratio_9_16',
      caption: {
        preset: 'wrap1',
        alignment: 'bottom',
        disabled: false
      },
      presetSettings: {
        mediaType: 'media'
      },
      language: 'en',
      addStickers: true,
      audio: {
        speed: 1,
        stability: 0.5,
        similarityBoost: 0.75,
        style: 0,
        useSpeakerBoost: true
      },
      webhook: 'https://yoursite.com/webhook',
      metadata: {
        contentType: 'marketing',
        topic: 'product-launch'
      }
    })
  });

  return await response.json();
};

With Gameplay

const createGamingVideo = async () => {
  const response = await fetch('https://api.tryhooked.ai/v1/project/create/prompt-to-video', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.HOOKED_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Gaming Tips Video',
      prompt: 'Create a video with three pro tips to level up gaming skills and dominate opponents. Make it energetic and engaging for gamers.',
      voiceId: 'energetic_voice_id',
      targetDuration: 45,
      presetSettings: {
        mediaType: 'gameplay'
      },
      gameplaySettings: {
        selectedGame: 'minecraft',
        selectedVideo: 'minecraft-1'
      },
      musicId: 'music_upbeat_01',
      aspectRatio: 'ratio_9_16',
      caption: {
        preset: 'beast',
        alignment: 'top',
        disabled: false
      },
      language: 'en',
      addStickers: true,
      audio: {
        speed: 1,
        stability: 0.5,
        similarityBoost: 0.75,
        style: 0,
        useSpeakerBoost: true
      },
      webhook: 'https://yoursite.com/webhook',
      metadata: {
        contentType: 'gaming',
        topic: 'tips'
      }
    })
  });

  return await response.json();
};

Short Video (30 seconds)

const createShortVideo = async () => {
  const response = await fetch('https://api.tryhooked.ai/v1/project/create/prompt-to-video', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.HOOKED_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      prompt: 'Share one mind-blowing fact about the ocean that most people dont know. Make it hook viewers in the first 3 seconds.',
      voiceId: 'confident_voice_id',
      targetDuration: 30,
      presetSettings: {
        mediaType: 'ai-images',
        preset: 'realistic',
        quality: 'pro'
      },
      aspectRatio: 'ratio_9_16',
      caption: {
        preset: 'tiktok',
        alignment: 'bottom',
        disabled: false
      },
      language: 'en',
      webhook: 'https://yoursite.com/webhook'
    })
  });

  return await response.json();
};

Long Video (120 seconds)

const createLongVideo = async () => {
  const response = await fetch('https://api.tryhooked.ai/v1/project/create/prompt-to-video', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.HOOKED_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      prompt: 'Create a comprehensive guide on how to start a morning routine that boosts productivity. Include wake-up habits, exercise tips, and mindset techniques.',
      voiceId: 'confident_voice_id',
      targetDuration: 120,
      presetSettings: {
        mediaType: 'ai-images',
        preset: 'cinematic',
        quality: 'ultra'
      },
      musicId: 'music_motivational_01',
      aspectRatio: 'ratio_16_9',
      caption: {
        preset: 'modern',
        alignment: 'bottom',
        disabled: false
      },
      language: 'en',
      addStickers: true,
      webhook: 'https://yoursite.com/webhook',
      metadata: {
        platform: 'youtube',
        category: 'self-improvement'
      }
    })
  });

  return await response.json();
};

Response

{
  "success": true,
  "data": {
    "videoId": "vid_p2v_abc123xyz",
    "projectId": "proj_p2v_abc123xyz",
    "status": "STARTED"
  },
  "message": "Prompt 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_p2v_abc123xyz",
    "status": "COMPLETED",
    "url": "https://cdn.tryhooked.ai/videos/abc123xyz.mp4",
    "shareUrl": "https://cdn.tryhooked.ai/shared/abc123xyz.mp4",
    "metadata": {
      "projectId": "proj_p2v_abc123xyz",
      "contentType": "educational"
    }
  },
  "message": "Video completed"
}

Your webhook endpoint must return a 200 status code. We’ll retry up to 3 times if the request fails.

Media Types

Available media types for presetSettings.mediaType:

Type	Description
`ai-images`	AI-generated images based on your generated 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

Target Duration Guide

Choose the right duration for your use case:

Duration	Use Case	Processing Time
30s	Quick tips, single facts, viral hooks	2-4 minutes
45s	Short tutorials, product highlights	3-5 minutes
60s	Standard explainers, listicles	4-6 minutes
90s	Comprehensive guides, deep dives	6-10 minutes
120s	Extended content, detailed tutorials	8-15 minutes

Best Practices

Write Clear Prompts

Be specific about the topic, tone, and target audience for better script generation.

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.

Prompt Writing Tips

Good Prompts

“Create an engaging video about the top 5 productivity tips for remote workers. Target busy professionals and use a motivational tone.” “Explain how blockchain technology works using simple analogies. Make it beginner-friendly and include real-world examples.” “Share 3 mind-blowing facts about space that most people don’t know. Hook viewers in the first 3 seconds.”

Avoid

“Make a video” (too vague) “Video about stuff” (no direction) “Something interesting” (unclear intent)

Error Handling

Error	Description	Solution
`prompt: Prompt is required`	Missing or empty prompt	Add the `prompt` field with your description
`prompt: Prompt cannot exceed 4000 characters`	Prompt too long	Shorten your prompt to under 4000 characters
`voiceId: Voice not found`	Invalid voice ID	Use a valid voice ID from `/v1/voice/list`
`targetDuration: Target duration must be at least 30 seconds`	Duration too short	Use minimum 30 seconds
`targetDuration: Target duration cannot exceed 120 seconds`	Duration too long	Use maximum 120 seconds
`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

prompt

string

required

Describe the video you want to create (1-4000 characters). The AI will generate a professional script from this prompt.

Required string length: 1 - 4000

targetDuration

number

default:60

required

Target duration for the generated video in seconds

Required range: 10 <= x <= 120

voiceId

string

required

Voice ID from /v1/voice/list

Maximum string length: 30

presetSettings

object

required

Settings for auto-generated media

Show child attributes

caption

object

required

Show child attributes

addStickers

boolean

default:false

required

Enable automatic sticker generation for the video

aspectRatio

enum<string>

default:ratio_9_16

required

Video aspect ratio

Available options:

ratio_9_16,

ratio_16_9,

ratio_1_1

language

enum<string>

default:en

required

Language code (2 characters)

Available options:

en,

es

Required string length: 2

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

object[]

Custom media items (max 50). If not provided, media will be auto-generated.

Maximum array length: 50

Show child attributes

gameplaySettings

object

Settings for gameplay footage

Show child attributes

audio

object

Voice audio settings

Show child attributes

webhook

string

HTTPS URL to receive completion notification

Maximum string length: 500

metadata

object

Custom metadata object (max 5KB)

Response

Prompt to Video created successfully

success

boolean

data

object

Show child attributes

message

string

Getting Started

Resources

Videos

Templates

Overview

Endpoint

Required Fields

Optional Fields

Request Examples

With AI-Generated Images

With AI-Generated Videos

With Custom Media

With Gameplay

Short Video (30 seconds)

Long Video (120 seconds)

Response

Webhook Notification

Media Types

Caption Presets

Target Duration Guide

Best Practices

Write Clear Prompts

Choose the Right Media Type

Match Voice to Content

Use Webhooks

Prompt Writing Tips

Good Prompts

Avoid

Error Handling

Next Steps

List Voices

List Music

List Videos

Webhooks Guide

Authorizations

Body

Response

Getting Started

Resources

Videos

Templates

​Overview

​Endpoint

​Required Fields

​Optional Fields

​Request Examples

​With AI-Generated Images

​With AI-Generated Videos

​With Custom Media

​With Gameplay

​Short Video (30 seconds)

​Long Video (120 seconds)

​Response

​Webhook Notification

​Media Types

​Caption Presets

​Target Duration Guide

​Best Practices

Write Clear Prompts

Choose the Right Media Type

Match Voice to Content

Use Webhooks

​Prompt Writing Tips

​Good Prompts

​Avoid

​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

Short Video (30 seconds)

Long Video (120 seconds)

Response

Webhook Notification

Media Types

Caption Presets

Target Duration Guide

Best Practices

Prompt Writing Tips

Good Prompts

Avoid

Error Handling

Next Steps