Overview
Script to Video turns a script you wrote into a narrated video. A voice reads the script and the screen is filled with AI images, AI video clips, media from your library, gameplay footage or motion graphics. It works well for explainers, social media videos and marketing content. Every request needsscript (up to 10,000 characters), voiceId (from GET /v1/voice/list) and mediaType. The create call answers with a projectId; the video itself arrives later (see Getting the video).
With AI-Generated Images
With AI-Generated Videos
Withai-videos, clips are chained frame to frame by default (presetSettings.isContinuous defaults to true). Set it to false for independent clips.
presetSettings also takes aiModel (an image model for ai-images, a video model for ai-videos; a model of the wrong kind answers 400) and characterIds (your saved characters), for both. quality applies to ai-videos (and to motion graphics), isContinuous only to ai-videos, and useCharacterReferenceImage only to ai-images with characterIds. 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
The narration plays over gameplay footage.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
Animated graphics generated from the script.presetSettings.motionStyleId picks the look (any id of Get Catalog with name=motion-styles, for example kinetic-typography or modern-saas; auto or no value lets the director choose), and motionGuidelines (up to 2,000 characters) steers it. Library media you send in media can be used in the graphics. presetSettings.quality applies here too. Motion graphics typeset their own copy, so caption and addStickers do not apply.
Getting the Video
The create call answers right away: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 Script to Video
Visual Style Presets
Some of the presets for thepresetSettings.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.
Use Cases
- 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 theHooked-Signature header as shown in Webhooks. Answer 200 quickly; Hooked tries 3 times with a 10-second timeout.