Skip to main content

Overview

Prompt to Video turns a short description into a narrated video: AI writes the script, a voice reads it, and the screen is filled with AI images, AI video clips, your library media, gameplay footage or motion graphics. Use it for quick explainers, social media content and marketing videos when you don’t want to write the script yourself. Every request needs prompt (up to 4,000 characters) and voiceId (from GET /v1/voice/list). mediaType defaults to ai-images and targetDuration to 60 seconds (10 to 120). The create call answers with a projectId; the video arrives later (see Getting the video).

With AI-Generated Images

With AI-Generated Videos

With ai-videos, clips are chained frame to frame by default (presetSettings.isContinuous defaults to true). presetSettings.aiModel picks a video model; an image model here answers 400.
presetSettings also takes aiModel for ai-images (an image model; a video model there answers 400), characterIds (your saved characters, for both; with ai-images also useCharacterReferenceImage), and for motion graphics quality, motionStyleId and motionGuidelines. quality applies to ai-videos and motion graphics, not to ai-images; isContinuous only to ai-videos. characterMode: "speaking" (with voiceProfile) makes the characters speak with the video model’s own voice: it needs ai-videos and a talking preset (talking-fruit, talking-objects, talking-organs), otherwise the request answers 400, and a speaking cast has no narrator settings, captions or stickers.

With Your Own Media

media is a list of media IDs from your Hooked library. An ID that does not exist or belongs to another team answers 400 with media: Media "<id>" not found.

With Gameplay

gameplaySettings.selectedGame is a game id of Get Catalog with name=games (for example minecraft, subway-s, gta), and selectedVideo is one of that game’s clips (for example minecraft-1). To use your own footage, send selectedGame: 'custom' and a video ID from your library as selectedVideo. Without gameplaySettings the video uses minecraft / minecraft-1.

With Motion Graphics

motionStyleId takes any id of Get Catalog with name=motion-styles (for example kinetic-typography, modern-saas). Leave motionStyleId out (or send auto) to let the director choose. Motion graphics typeset their own copy, so caption and addStickers do not apply.

Getting the Video

The create call answers right away:
Then either wait for your webhook (below) or poll the project:
Send an Idempotency-Key header to retry safely: if a request times out or answers 5xx, sending it again with the same key and body returns the first answer instead of creating (and charging) the project twice.
Teams in bring-your-own-keys mode are not charged credits for generation, but need their own provider keys in Settings → AI keys: OpenRouter always, ElevenLabs for the narration (not needed when AI video characters speak in their own voice, characterMode: "speaking"), and Gemini when the AI video model is Omni 1.1 Flash. A missing key answers 402 with code: "missing_credentials" and the list in missingProviders, before anything is created.

Tips for Prompt to Video

Be specific: Include topic, tone, and target audience in your prompt for better script generation
Match media to content: Use ai-images for explainers, gameplay for gaming, media for your brand footage, motion-graphics for SaaS and data stories
Choose duration wisely: 30s for quick tips, 60s (the default) for standard content, 90-120s for longer guides
Choose the right voice: Match voice tone to your content - energetic for gaming, professional for business
Use background music: Add music to enhance engagement without overpowering the narration

Visual Style Presets

Some of the presets for the presetSettings.preset field (used with ai-images and ai-videos; default realistic): presetSettings.quality is base (default), pro or ultra; it applies to ai-videos and motion-graphics, not to ai-images.

Media Types

Caption Presets

caption.preset takes any id of Get Catalog with name=caption-presets (for example wrap1, tiktok, beast, classic); the default here is wrap1. Captions are on unless you send caption.disabled: true.

Target Duration Guide

targetDuration is in seconds, any value from 10 to 120 (default 60). The script is written to fit it, in the language you send (or the prompt’s); the final length can differ by a few seconds.

Use Cases

  • Quick Content Creation: Generate videos from simple descriptions without writing scripts
  • Educational Content: Explainers, tutorials, how-to videos
  • Social Media: TikTok, Instagram Reels, YouTube Shorts
  • Marketing: Product showcases, brand stories, promotions
  • Gaming: Tips, tutorials, compilations
  • News & Updates: Company announcements, industry updates

Handling the Webhook Response

Webhooks are signed: check the Hooked-Signature header as shown in Webhooks. Answer 200 quickly; Hooked tries 3 times with a 10-second timeout.