generate_topic_short
Generate a Topic Short from a reviewed storyPlan or automatically plan one from the topic and storyFormat. Spoken narration fills the selected length. A short reviewed plan is expanded so the voiceover is not a music-only tail. A too-long plan is packed down; generate never fails for narration length. captionStyle defaults to spotlight (off, spotlight, impact, highlighter, editorial, boxed, kicker — the Story caption looks, burned from the voiceover word timings); transitionMode defaults to dynamic. Uses this month’s generation allowance or complimentary quota. Poll get_topic_short. Stock matching fail-opens: a Pexels miss or outage still returns a finished short. Caption failure also fail-opens (captionBurn.verdict = fallback). Legacy captionMode values are aliased onto captionStyle. Optional hookTemplateId seeds the topic from Opening hooks (script opening, not a caption look) and does not change consume or refund. Takes the same setup as quote_topic_short (storyFormat, aspectRatio, visualStyle, aiHook, language, host, sources, voiceCloneId, seriesEpisodeId); pass the same values on both. Cinematic and AI hook shots that miss their 2-minute deadline fall back to judged stock, so the short still ships. A seriesEpisodeId short is linked to that episode.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| topic | No | Topic to plan from. Required unless hookTemplateId seeds it or seriesEpisodeId supplies it. An explicit topic wins over either seed. | |
| voice | No | Narration voice id from list_audio_lab_voices. Defaults to the product default voice. | |
| aiHook | No | Optional AI hook: the opening shot is an AI clip and abstract beats can get AI stills; the rest stays judged stock. Quoted higher. Any AI shot that misses its 2-minute deadline falls back to the best stock clip. Not available on the free short. | |
| format | No | Alias of storyFormat. storyFormat wins when both are set. | |
| script | No | Optional supplied narration. If it already fills the selected length it is preserved word for word; if it is too short the planner expands it so speech fills the duration. Too-long scripts are packed down to the speaking-pace envelope (never fail generate for narration length). Maximum 8,192 UTF-8 bytes. | |
| quoteId | No | Quote id from quote_topic_short. Optional; generate quotes first when omitted if topic is set. | |
| sourced | No | Sourced script: research the topic, cite real sources, and soften or drop claims it cannot verify. The finished short carries a Sources card; get_topic_short returns the citations. Implied by sourceUrl, sourceUrls or sourceText. Not available on the free short. | |
| language | No | Narration and caption language: en (English), es (Spanish), pt (Portuguese), de (German), fr (French), hi (Hindi). Default en. The planner writes the script in this language; pass a script already written in it. Stock search terms stay English. | en |
| sourceUrl | No | One https article or page link that grounds a sourced script. Same as a one-item sourceUrls. | |
| storyPlan | No | Optional reviewed story from create_topic_short_story. Pass the same plan when quoting and generating; omit to plan automatically. A plan whose narration is too short for the selected length is expanded at generate so speech fills the duration. A too-long plan is packed down; generate never fails for narration length. | |
| characters | No | auto (default) keeps one recurring fictional character consistent across shots on story formats (story_twist, mini_documentary) with cinematic or aiHook; off turns that off. Real people are never generated. | |
| hookBlanks | No | Fill [bracket] keys from the Opening hooks seed. Example: { "the annoying thing": "soggy leftovers" }. Does not change the quote. | |
| hookIntent | No | Optional Opening hooks intent. Browse with list_hook_bank. Ignored when seeding if hookTemplateId is set. | |
| hostLayout | No | Where the host appears: pip_circle (default), pip_corner, or full frame. Only with hostNarratorId. | pip_circle |
| sourceText | No | Pasted article text (200–20,000 characters) that grounds a sourced script. | |
| sourceUrls | No | Up to 3 https links that ground a sourced script. PDF uploads are website-only; paste the text with sourceText instead. | |
| aspectRatio | No | Frame size. 9:16 vertical (default), 16:9 landscape, or 1:1 square for feeds. | 9:16 |
| captionMode | No | Legacy Topic Shorts caption mode, accepted for old clients only. current maps to spotlight, hook to impact, phrase to kicker, off to off. Prefer captionStyle. | |
| storyFormat | No | Storytelling format: mini_documentary (Mini documentary), myth_check (Myth check), story_twist (Story with a twist), how_it_works (How it works), ranking (Top 5), quiz (Quiz), scary_story (Scary story), history_pov (History POV), reddit_story (Post story), what_if (What if). Defaults to mini_documentary. Each format has its own pacing, cards and music mood. | |
| visualStyle | No | Visual style: standard (judged stock footage, default) or cinematic (every shot is an AI keyframe animated to video). Cinematic is quoted higher and takes a few minutes longer. Not available on the free short. Real people and brands are never AI-generated. | standard |
| captionStyle | No | Topic Short caption look: off, spotlight (default — each spoken word lights up on a blue highlight), impact (bold outlined caps, two words at a time), highlighter (caps with one yellow key word), editorial (quiet lower-third phrases), boxed (phrases on a rounded dark pill), or kicker (phrase chunks with one oversized cyan word up top). Same seven looks as Story; burned by the API from the voiceover word timings, in the narration language (Hindi uses a Devanagari font). Does not change the quote amount. Caption failure still returns a finished short. | spotlight |
| recipeSource | No | With recipeGenerationId: part_two makes Part 2 of that short; same_style reuses only its setup for a new topic. Pass the same value when quoting and generating. | part_two |
| voiceCloneId | No | Optional id of one of your ready cloned voices (list_topic_short_voice_clones). Replaces voice. Paid plans only. Shorts narrated with a clone keep the AI-voice disclosure unless it was turned off when the voice was recorded. | |
| hookTemplateId | No | Optional Opening hooks template (catalog id hook_bank). The workspace picker is hidden. Seeds topic or Talking Shorts brief when that field is empty. Fill [brackets] via hookBlanks or by editing the seeded text. This is a script opening, not a caption look (captionStyle). Does not change the quote, consume, or refund. | |
| hostNarratorId | No | Optional recurring host: a Character Films narrator (list_character_film_catalog) who appears lip-synced in the hook and outro. Quoted higher. Not available on the free short. | |
| idempotencyKey | No | Reuse this key and the same quoteId and inputs when retrying an ambiguous submission. | |
| transitionMode | No | Classic current cuts and dissolves, Dynamic punchier motion (default), or Off hard cuts. Does not change the quote. | dynamic |
| captionsEnabled | No | Legacy on/off. Prefer captionStyle. false selects Off captions. | |
| durationSeconds | No | Target length of the finished short in seconds (15–180). Spoken narration is written to fill this length. Quoted on this duration, not word count. | |
| seriesEpisodeId | No | Optional approved episode id from queue_topic_short_episodes. Uses that episode as the topic (when topic is empty) and the series style as the setup; explicit arguments still win. The short is linked to the episode. Quoted like any other short. | |
| recipeGenerationId | No | Optional id of one of your earlier Topic Shorts (from generate_topic_short or get_topic_short). Copies its setup: voice, caption look, transitions, format, frame size, length and shot length. Any setting you pass explicitly wins. Never copies the topic, script or plan. Does not change how the short is priced. Pass the same value when quoting and generating. | |
| clipDurationSeconds | No | Length of each stock B-roll clip in seconds (2–6, default 3). Not the full short length. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | Job status such as pending, queued, in_progress, completed, or failed. | |
| videoId | No | Library clip id for this job, when one exists. | |
| idempotent | No | True when this call reused an in-flight or finished job with the same idempotency key. | |
| generationId | Yes | Generation id. Poll the matching get_* tool until status is completed or failed. | |
| creditsCharged | No | Usage already consumed from this month’s generation allowance (internal units). |