niche_render_reel

{
  "type": "object",
  "properties": {
    "session_id": {
      "type": "string",
      "description": "Session UUID that's reached cp3_awaiting_review or complete."
    },
    "scope": {
      "type": "string",
      "description": "'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."
    },
    "beat_direction": {
      "type": "string",
      "description": "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."
    },
    "captions_enabled": {
      "type": "boolean",
      "description": "Overlay caption text on each beat. Default true. With scope='recomposite': omit to keep the reel's current setting."
    },
    "endcard_text": {
      "type": "string",
      "description": "scope='recomposite'/'endcard' only: the big endcard words (replaces the brand stamp text). Omit to keep the current endcard."
    },
    "endcard_outro": {
      "type": "string",
      "description": "scope='recomposite'/'endcard' only: the smaller endcard line under the mark. Omit to keep the current one; pass '' to clear it."
    },
    "music_enabled": {
      "type": "boolean",
      "description": "Mix background music behind the voiceover. Default false."
    },
    "tone": {
      "type": "string",
      "enum": [
        "default",
        "punchy",
        "direct",
        "reflective"
      ],
      "description": "Script tone hint (scope='full'). Default 'default'. For direction beyond these four, use reel_direction."
    },
    "reel_direction": {
      "type": "string",
      "description": "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."
    },
    "length": {
      "type": "string",
      "enum": [
        "short",
        "standard",
        "long"
      ],
      "description": "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."
    },
    "target_duration_sec": {
      "type": "integer",
      "description": "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."
    },
    "music_direction": {
      "type": "string",
      "description": "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."
    },
    "voice": {
      "type": "string",
      "description": "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'."
    },
    "endcard_mark": {
      "type": "string",
      "enum": [
        "logo",
        "wordmark",
        "headshot",
        "text"
      ],
      "description": "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_color": {
      "type": "string",
      "description": "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'."
    },
    "motion": {
      "type": "string",
      "description": "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."
    },
    "needs_legible_text": {
      "type": "boolean",
      "description": "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."
    },
    "caption_sync_mode": {
      "type": "string",
      "enum": [
        "beat",
        "phrase"
      ],
      "description": "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."
    },
    "cell": {
      "type": "string",
      "description": "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)."
    },
    "estimate_only": {
      "type": "boolean",
      "description": "If true, return {credit_cost} without rendering or spending. Use to learn the cost before committing.",
      "default": false
    }
  },
  "required": [
    "session_id"
  ]
}