Skip to main content

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 needs script (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

With ai-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:
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 Script to Video

Structure your script: Break content into clear sections with natural pauses for better pacing
Match media to content: Use ai-images for explainers, gameplay for gaming, media for your brand footage, motion-graphics for SaaS and data stories
Keep it concise: 30-90 seconds works best for social media content
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.

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 the Hooked-Signature header as shown in Webhooks. Answer 200 quickly; Hooked tries 3 times with a 10-second timeout.