Recipes Overview

Recipes are the higher-level guided path in ReelForger.

Use them when you want to describe what you want to produce and let ReelForger handle most of the timeline assembly details.

Use this path when / do not use this path

Use Recipes when

• A known output pattern matches the request (explainer, slideshow, listicle, caption clip).
• You want high reliability with less payload complexity.
• You want recipe_id + variables to be the primary authoring model.

Do not use Recipes when

• You need explicit control over custom layer math, overlap, or advanced layout choreography.
• You need composition behavior outside recipe controls.

Switch paths if needed

• Start here first, then move to Timeline Overview when recipe controls are insufficient.
• Use Supported Output Patterns when intent is broad and you need nearest-pattern matching.

Why use Recipes first

• Less payload complexity than hand-writing timeline manifests
• Stable request shapes for AI agents
• Built-in pacing and composition defaults for common formats
• Faster time-to-first-output for most use cases

Canonical route and field

• Route: POST https://api.reelforger.com/v1/recipes/render
• Canonical identifier field: recipe_id

Inline transcription in recipes

Caption-capable recipes support inline transcription:

• If variables.transcript_words is supplied, ReelForger uses it directly.
• If variables.transcript_words is omitted, ReelForger may transcribe automatically from the recipe's obvious speech source.
• If a recipe ever has ambiguous speech source selection, provide variables.transcription_source_asset_id.
• If correct_text is supported by that recipe, it remains usable with auto-transcription for punctuation/casing polish.
• Current behavior: auto-transcription uses the full selected source duration sent for transcription (no smart subsection trimming yet).

Recipes vs Timeline

Use this decision rule:

• Choose Recipes if the format matches a known pattern (explainer, slideshow, listicle, caption clip)
• Choose Timeline API if you need custom layer math or behavior beyond recipe controls

Side-by-side comparison

Path	Best for	Request style	Typical tradeoff
Recipes	Guided common outputs	recipe_id + variables	Less low-level control
Timeline API	Fully custom compositions	full version/output/assets/composition manifest	More manual setup

Recommended workflow

1. Choose a recipe
2. Prepare variables payload
3. Validate the request body
4. Render
5. Poll https://api.reelforger.com/v1/jobs/{jobId} or use webhooks

Canonical execution flow

1. Choose path (Recipes or Timeline)
2. Validate payload with POST https://api.reelforger.com/v1/videos/validate (recommended)
3. Render with POST https://api.reelforger.com/v1/recipes/render or POST https://api.reelforger.com/v1/videos/render
4. Capture job_id from 202 Accepted
5. Retrieve via GET https://api.reelforger.com/v1/jobs/{jobId} or webhooks
6. Handle failures and retry safely with idempotency keys

Recipe categories

• Core recipe pages: voiceover_explainer, photo_slideshow, listicle_ranked, captioned_clip
• Coming soon: storytime_broll
• Workflows: implementation walkthroughs (AI Influencer Workflow is currently marked Coming soon)