ReelForge DocsAgent-First API
OpenAPIllms.txtSign inMain site

Timeline Request Structure

Timeline requests use a full render manifest shape.

Need the short mental model first? See Timeline Overview timing inference model.

Endpoint

  • Render: POST https://api.reelforger.com/v1/videos/render
  • Validate: POST https://api.reelforger.com/v1/videos/validate

Top-level structure

{
  "version": "v1",
  "output": { "width": 1080, "height": 1920, "fps": 30 },
  "assets": [],
  "composition": {}
}

Required fields

  • version
  • output.width, output.height, output.fps
  • composition object

At least one visual/audio path must be represented through composition.timeline and corresponding assets.

Optional but common fields

  • idempotency_key (safe retry dedupe)
  • composition.auto_stitch (derive sequencing by layer order)
  • composition.text_overlays
  • composition.captions
  • webhook_url, webhook_headers, webhook_secret
  • metadata

Assets and layer linkage

  • Each timeline layer references an asset via asset_id.
  • Every asset_id must exist in assets[].
  • Layer type and asset type should match intended usage.

Time rules

  • image layers require time.start_seconds.
  • image.time.duration_seconds can be omitted when composition duration is inferable:
    • from explicit composition.duration_seconds,
    • from max timed end across timeline/text overlays,
    • or at render-time when composition.auto_stitch is enabled and media durations are probed.
  • video/audio layers require time unless composition.auto_stitch is true.
  • trim.start_seconds is optional for audio/video.

Captions and alignment

  • Use composition.captions.words as raw timing source.
  • Add composition.captions.correct_text when you need improved punctuation/casing alignment.
  • Keep caption placement in safe lower-third regions for social readability.

Validate first

Use https://api.reelforger.com/v1/videos/validate with the exact same body before rendering in production. Warnings highlight common readability/layout/timing risks before credits are spent.