ReelForger LogoDocumentation
Sign inGet Started

Recipe: captioned_clip

Status: Live

Transcript-driven clip recipe for podcast/interview formats with full-frame or split-screen layout.

Bridge Note

Recipes are the recommended path. Use https://api.reelforger.com/v1/recipes/render as the canonical endpoint.

When to use it

  • You have spoken-video clips
  • You need caption-forward social clipping quickly

Input assets

This example uses the following assets:

Required inputs

  • primary_video_url
  • layout_variant
  • style_preset

Optional overrides

  • transcript_words (when you already have timestamps)
  • transcription_source_asset_id (when words are omitted and source inference is ambiguous)
  • correct_text (punctuated reference for caption alignment)
  • secondary_video_url (required for split_screen)
  • cta_text
  • cta_style/layout
  • captions_mode (phrase_karaoke default; supports phrase and word_only)
  • captions_style/layout

Request structure

  • Send requests to https://api.reelforger.com/v1/recipes/render.
  • Use canonical field recipe_id.
  • Keep style_preset at the root and recipe-specific values inside variables.

Variable behavior guide

  • primary_video_url: main speaking clip.
  • layout_variant: full_frame or split_screen mode.
  • transcript_words: optional timestamped word timing source; if omitted, ReelForger may transcribe inline.
  • transcription_source_asset_id: optional explicit speech source override when words are omitted.
  • correct_text: cleaned transcript to improve punctuation alignment.
  • captions_mode: phrase_karaoke, phrase, or word_only behavior.
  • captions_layout / captions_style: readability and placement tuning.

Payload and output preview

Payload example

{
  "recipe_id": "captioned_clip",
  "style_preset": "karaoke_yellow",
  "variables": {
    "primary_video_url": "https://pub-2ad5592bc4ca44abb609acfc0b7c5ceb.r2.dev/reel-forge-website-assets/talking%20head%20runner.mp4",
    "layout_variant": "full_frame",
    "captions_mode": "phrase_karaoke",
    "captions_layout": { "y": "72%" }
  }
}

Output preview

Talking-head clip with Karaoke Yellow captions, correct_text for punctuation alignment.

Constraints

  • secondary_video_url is required when layout_variant=split_screen
  • If transcript_words is omitted, ReelForger may auto-transcribe from the selected speech source
  • Auto-transcription currently uses the full selected source duration and bills 1 credit per 5 seconds (rounded up) on successful transcription

Common mistakes and errors

  • Choosing split_screen without secondary_video_url
  • Supplying unsorted transcript_words tokens when providing words directly
  • Providing a transcription_source_asset_id that does not exist in the recipe manifest source set
  • Providing correct_text that diverges heavily from recognized speech, which can cause caption_alignment_failed

Make/Zapier mapping tips

  • Map incoming speaker clip URL to primary_video_url and optional B-roll URL to secondary_video_url.
  • If your no-code tool has branching, only include secondary_video_url when layout_variant is split_screen.
  • Either feed transcript_words directly from STT output or omit transcript_words to let ReelForger transcribe inline.
ReelForger