quote_topic_short
Read-only
Quote a Topic Short. Does not render. Spoken narration is planned to fill the selected length; that does not change the quote (quoted on duration, not word count). captionStyle defaults to spotlight (same seven looks as Story: off, spotlight, impact, highlighter, editorial, boxed, kicker); transitionMode defaults to dynamic. Neither changes the quote. 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 the quote. The setup that does change the quote: length, visualStyle cinematic, aiHook (and the recurring characters they bring on story formats), a host (hostNarratorId) and sourced research; language, aspectRatio (9:16, 16:9, 1:1), storyFormat and a cloned voice (voiceCloneId) do not change the price. Cinematic, aiHook, host, sourced and voice clone are paid options, not available on the free short. seriesEpisodeId quotes an approved series episode with its series style.
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. | |
| 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. | |
| 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 |
|---|---|---|---|
| credits | No | Usage this quote would consume from this month’s generation allowance (internal units). | |
| quoteId | Yes | Quote id. Pass this to the matching generate tool. Quotes expire. | |
| expiresAt | No | ISO timestamp when this quote expires. | |
| pricingVersion | No | Pricing version used for this quote. |