Render a reel
niche_render_reelRender a 9:16 vertical reel for a session at CP3. A per-beat script (typically 4-7 beats) is composited into one video: stills, voiceover, motion, caption overlays, and an endcard (~30-120s). Reels are delivered as a downloadable file for the user to publish.
scope: 'full' (default) renders a new reel. 'recomposite' re-renders presentation only (captions on/off, caption_sync_mode, endcard text) from the retained footage at no charge. 'endcard' is the same, limited to the endcard. 'beat:N' re-renders a single beat's still (optional beat_direction), charged for that one image; everything else is reused.
Idempotent on the video output: a prior render is replaced.
Options: captions_enabled (default true) overlays per-beat captions; music_enabled (default false) mixes background music under the voiceover; tone shapes the script (default | punchy | direct | reflective), with reel_direction for free-form direction beyond those words; length or target_duration_sec set the runtime target; music_direction shapes the music; voice picks the voiceover voice; endcard_mark chooses the endcard brand mark; needs_legible_text forces a text-capable still generator; caption_sync_mode (default 'phrase') reveals captions phrase-by-phrase in sync with the voiceover at no extra cost, and is ignored when captions_enabled is false.
Errors: 503 if reel rendering is unavailable; 400 before CP3; 422 if the script is unusable. Cost: ~350 credits.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cell | No | Optional. Cell to tag the rendered Output row (linkedin:reel / x:reel / instagram:reel). All reels are 9:16 1080×1920 universal, so cell only affects bookkeeping, not pixels. When omitted: stored under platform='video' (shared across all reel cells). | |
| tone | No | Script tone hint (scope='full'). Default 'default'. For direction beyond these four, use reel_direction. | |
| scope | No | 'full' (default): render a new reel (script plus stills plus voiceover, ~350 credits). 'recomposite': re-render presentation from the retained footage (captions on/off, caption_sync_mode, endcard_text/endcard_outro), at no charge, async. 'endcard': the same, limited to the endcard (endcard_text/endcard_outro/endcard_mark; use 'recomposite' to change captions). 'beat:N': re-render shot N's still (1-based, optional beat_direction and motion), ~15 credits; everything else is reused. Script changes (tone, voiceover words, music) require scope='full'. Partial scopes require a reel whose footage was retained, otherwise the response indicates scope='full' is needed. | |
| voice | No | scope='full': voiceover voice for this render, overriding the brand kit's saved preference just this once. Use 'auto', 'male', or 'female', or a short hint like 'a warm female narrator'. | |
| length | No | scope='full': total runtime target the script is budgeted to hit. 'short' ~10-15s, 'standard' ~15-22s, 'long' ~25-40s. For an exact number of seconds, use target_duration_sec instead. | |
| motion | No | scope='beat:N': the Ken Burns motion for the re-rolled shot ('zoom-in', 'zoom-out', 'static', or a plain steer like 'slow push-out'). Overrides that shot's existing motion. Omit to keep the current motion. | |
| session_id | Yes | Session UUID that's reached cp3_awaiting_review or complete. | |
| endcard_mark | No | Which brand mark stamps the endcard for this render, overriding the brand kit's saved preference just this once (e.g. end on the logo, not the name). Honored on scope='full', 'recomposite', and 'endcard'. Falls back to the brand name text when the chosen asset is not set on the kit. | |
| endcard_text | No | scope='recomposite'/'endcard' only: the big endcard words (replaces the brand stamp text). Omit to keep the current endcard. | |
| endcard_color | No | The endcard background color, a name or hex ('navy', '#0a3d62'), overriding the brand color on the closing frame just this once. The endcard text re-resolves to stay legible on it. Honored on scope='full', 'recomposite', and 'endcard'; ignored on 'beat:N'. | |
| endcard_outro | No | scope='recomposite'/'endcard' only: the smaller endcard line under the mark. Omit to keep the current one; pass '' to clear it. | |
| estimate_only | No | If true, return {credit_cost} without rendering or spending. Use to learn the cost before committing. | |
| music_enabled | No | Mix background music behind the voiceover. Default false. | |
| beat_direction | No | scope='beat:N' only: optional plain-language steer for the re-rolled shot ('warmer light, no people'). Omit for a fresh take on the same brief. | |
| reel_direction | No | scope='full': free-form creative direction applied alongside tone, for steers the four tone words do not cover (pacing, narrative shape, mood), e.g. 'courtroom-drama narration, build to a reveal'. The free-form sibling of tone. | |
| music_direction | No | scope='full': free-form style, genre, and tempo for the background music, e.g. 'calm lo-fi, no vocals'. Supplying it turns music on for this render. Music is generated audio, so a free re-render or shot re-roll cannot change it. | |
| captions_enabled | No | Overlay caption text on each beat. Default true. With scope='recomposite': omit to keep the reel's current setting. | |
| caption_sync_mode | No | How captions track the voiceover. 'beat' (default): each beat's caption shows for that beat's spoken window. 'phrase': the caption reveals phrase-by-phrase in lockstep with the spoken words (caption text is taken from the spoken VO). Ignored when captions_enabled is false. No extra cost. | |
| needs_legible_text | No | scope='full': force the text-capable still generator for every shot, for a reel whose stills carry readable words. Default false lets each shot pick the best generator on its own. | |
| target_duration_sec | No | scope='full': exact total runtime target in seconds (8 to 45). Wins over `length`. The script budgets each beat to land near this total; the delivered duration can vary by a second or two. |