Timeline Overview

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

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}

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

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