ReelForger LogoDocumentation
Sign inGet Started

Timeline Overview

Timeline API is the lower-level custom composition path in ReelForger.

Use it when you need explicit control over assets, layers, timing, layout, and rendering behavior that goes beyond recipe-level controls.

Use this path when / do not use this path

Use Timeline API when

  • You need custom composition behavior beyond recipe controls.
  • You need explicit per-layer control over timing, placement, and overlap.
  • You are authoring full manifests as your primary model.

Do not use Timeline API when

  • A recipe already matches the user request and speed is the priority.
  • You do not need low-level layout/timing control.

Switch paths if needed

  • If a recipe can meet the request, prefer Recipes Overview first.
  • If a recipe attempt cannot express needed behavior, switch back to Timeline and keep validate-first flow.

How Timeline relates to Recipes

  • Recipes are guided abstractions for common formats.
  • Timeline API is the underlying composition model for full customization.

If a recipe can express your target output, start there first.
Switch to Timeline when you need custom sequencing, overlap logic, split layouts, or layer-by-layer tuning.

When to use Timeline

  • Custom compositions beyond available recipes
  • Precise multi-layer timing control
  • Advanced layout/overlap behavior
  • Detailed per-layer media and style control

Core endpoints

  • Validate: POST https://api.reelforger.com/v1/videos/validate
  • Render: POST https://api.reelforger.com/v1/videos/render
  • Retrieve: GET https://api.reelforger.com/v1/jobs/{jobId}

Inline caption transcription (Timeline)

Timeline supports inline transcription for captions:

  • If composition.captions.words is supplied, ReelForger uses it directly.
  • If composition.captions.words is omitted, ReelForger may transcribe automatically.
  • If ReelForger cannot infer a single speech source, you must set composition.captions.transcription_source_asset_id.
  • You can still provide composition.captions.correct_text to polish punctuation/casing while using auto-transcribed words.
  • Current behavior: ReelForger transcribes the full selected source duration sent for transcription.

Timing inference model

Timeline timing can be a mix of explicit and inferred values:

  • Explicit layer timing always wins when provided.
  • video / audio layer time can be omitted when composition.auto_stitch: true.
  • image layers require time.start_seconds; time.duration_seconds can be inferred.
  • Image duration inference order:
    1. explicit image time.duration_seconds
    2. composition.duration_seconds
    3. max timed end across composition.timeline + composition.text_overlays
    4. render-time media probing when auto_stitch untimed media is present
  • When auto_stitch is enabled, untimed video layers are sequenced in timeline order (stitched back-to-back).
  • In mixed timelines, untimed audio layers default to start_seconds: 0 and are aligned to the stitched video duration, so they overlap unless you provide explicit time.
  • Text overlays still count toward inferred composition duration even though they live outside composition.timeline.
  • If you mix timed and untimed media layers, validate first so the inferred composition length is obvious before render.

Execution flow

The canonical end-to-end decision tree and execution loop are owned by Start Here for Agents. Use this page for Timeline-specific behavior and field guidance.

Section map

  • Examples: copyable payload patterns to learn common composition shapes
  • Reference: field-level behavior, validation guidance, and jobs/webhooks details
ReelForger