ReelForger LogoDocumentation
Sign inGet Started

Machine-readable discovery

Use llms.txt and openapi.json for agent discovery and contract parsing.

Let your AI agent guide the implementation

Copy this prompt into ChatGPT, Claude, or another AI agent. It will start by reading the ReelForger docs from llms.txt, then ask you the right questions about what you want to create, what assets you have, and what constraints matter before helping you build the correct API request.

You are my ReelForger implementation assistant.

Start by reading the ReelForger machine-readable docs here:
https://www.reelforger.com/llms.txt

Your role is to help me work out how to create what I want with the ReelForger API.

Important instructions:
- Read the docs first before recommending anything.
- Do not assume I have already provided everything you need.
- Lead the conversation step by step.
- Ask me what I am trying to create.
- Ask me what assets I already have available.
- Ask me about any important constraints or preferences such as format, dimensions, style, branding, timing, captions, overlays, logos, motion, voiceover, platform, or automation tool.
- Help me identify what is missing.
- Recommend the best ReelForger endpoint or workflow based on the docs.
- Once you have enough information, produce the exact JSON request body I should send.
- Where useful, use placeholders like {{video_url}}, {{audio_url}}, {{logo_url}}, {{image_1}}, {{image_2}} so I can use it in Make.com or another automation tool.
- Prefer practical implementation guidance over abstract explanation.

How to respond:
1. First, briefly confirm you have read the ReelForger docs.
2. Then ask me the most useful questions needed to understand:
   - what I want to create
   - what assets I have
   - what constraints or preferences I have
3. After I answer, recommend the best endpoint or workflow.
4. Then tell me if anything is missing or needs transforming first.
5. Then give me the final JSON request body.
6. Then give me a short implementation note for Make.com if relevant.

Please begin by reading the docs and then briefly asking me your first questions.

Start Here for Agents

Page role: this page shows how to use ReelForger end-to-end, from path selection to async retrieval.

Use this page when you are an agent (or building one) and need a practical orientation before generating requests.

What ReelForger is for

ReelForger is an AI-agent-native media engine and the easiest video API for AI agents.

It assembles short-form social video from structured inputs:

  • Media URLs (video, image, audio)
  • JSON payloads that define timing/layers/captions
  • Async retrieval through jobs or webhooks

Supported output families

Common supported patterns include:

  • Captioned talking-head clips
  • Voiceover explainers
  • Photo slideshows
  • Ranked listicles
  • Stitched clip reels
  • Split-screen videos
  • Text-overlay videos

Use the Supported Output Patterns page to map broad user goals to the nearest supported path.

Choose interface first

  • Use MCP (https://mcp.reelforger.com/mcp) for agent/tool-native execution workflows.
  • Use raw API (https://api.reelforger.com/v1/openapi.json) for direct HTTP integrations or lower-level contract control.
  • Raw API remains the source of truth; MCP is a thin execution layer over it.

If the user needs generated music before rendering, use the Music API first. Each successful music generation request costs 20 credits and always returns 2 reusable tracks that can then be fed into a normal render workflow.

Choose your render path

Use Recipes when

  • You want the fastest reliable path for common formats
  • You can express intent as recipe_id + variables
  • You prefer guided defaults over low-level layer math

Use: POST https://api.reelforger.com/v1/recipes/render with canonical field recipe_id.

Use Timeline API when

  • You need custom composition behavior not covered by recipe controls
  • You need explicit control over layers/timing/layout/media behavior
  • You need advanced sequencing or overlap logic

Use: POST https://api.reelforger.com/v1/videos/render with full manifest fields.

Timeline is the powerful custom path. Use it when recipe controls are insufficient and you need direct control over layout, timing, overlap, layering, and media behavior.

Optional: generate music before render

Use Music API when

  • The user does not already have a music URL
  • The user wants ReelForger to generate reusable background music from a prompt
  • The user wants to compare 2 returned tracks before choosing one for the final render

Use:

  • POST https://api.reelforger.com/v1/music/generate
  • GET https://api.reelforger.com/v1/music/jobs/{jobId}

Then take one returned tracks[].audio_url value and use it in a normal Recipes or Timeline render request.

  1. Choose render path (Recipes or Timeline API)
  2. If needed, generate music with POST https://api.reelforger.com/v1/music/generate
  3. Poll GET https://api.reelforger.com/v1/music/jobs/{jobId} until 2 tracks are returned
  4. Validate render payload with POST https://api.reelforger.com/v1/videos/validate
  5. Render (POST https://api.reelforger.com/v1/recipes/render or POST https://api.reelforger.com/v1/videos/render)
  6. Capture job_id from 202 Accepted
  7. Retrieve output:
    • Poll GET https://api.reelforger.com/v1/jobs/{jobId}, or
    • Receive webhook events via webhook_url
  8. Handle failures using structured errors and retry with idempotency keys

Validation is a dry-run/schema-and-warning checkpoint; it does not queue a job or consume credits.

MCP equivalent loop:

  1. Call render_recipe or render_timeline at https://mcp.reelforger.com/mcp
  2. Capture job_id
  3. Poll get_job_status until terminal status
  4. Read output URL, billing, and errors from status payload

Inline caption transcription behavior

For captioned renders (Recipes and Timeline), use this rule consistently:

  • If words are supplied, ReelForger uses them directly.
  • If words are omitted, ReelForger may transcribe automatically.
  • If source selection is ambiguous, you must provide transcription_source_asset_id.
  • If correct_text is supported in the chosen flow, you can still provide it with auto-transcription for caption polish.
  • Current behavior: ReelForger transcribes the full selected source duration that is sent for transcription.

Canonical simplified captioned request (omitted words)

{
  "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"
  }
}

Timing note (agent default)

When building Timeline payloads, do not assume every layer must include explicit duration:

  • With composition.auto_stitch: true, untimed video layers are stitched in order; in mixed timelines, untimed audio defaults to start_seconds: 0 and is aligned to stitched video duration unless explicit time is provided.
  • Image layers require time.start_seconds; image time.duration_seconds can be inferred from composition timing context.
  • If timing context is still ambiguous, set composition.duration_seconds explicitly.

If you are still unsure

  1. Start with Recipes.
  2. Use a nearest pattern from Supported Output Patterns.
  3. Validate first, then render.
  4. Escalate to Timeline only if recipe controls are insufficient.

Canonical examples (CI-backed)

These examples are maintained as executable golden flows in the docs E2E harness:

  • Talking head + captions + logo (Timeline path)
  • Talking head + captions + logo + background music (Timeline path)
  • Image slideshow + narration + music (Recipe path)
ReelForger