Recipe: listicle_ranked

Status: Live

Ranked countdown recipe for Top-N clips with optional intro title, timed item labels, and optional CTA.

Bridge Note

Recipes are the recommended path. Use https://api.reelforger.com/v1/recipes/render as the canonical endpoint.

When to use it

You are producing countdown/ranked social content
You need hook/items/CTA pacing from one soundtrack

Input assets

This example uses the following assets:

Required inputs

background_audio_url
hook_title
items (min 2)
style_preset

Optional overrides

background_audio_start_seconds (trim start of soundtrack)
background_audio_duration_seconds (cap total duration, max 60s)
hook_duration_seconds (set to 0 to skip hook)
title_text / title_duration_seconds (separate intro title overlay)
countdown_mode (render labels as #N -> #1)
cta_text
hook_style/layout
item_title_style/layout
cta_style/layout

Request structure

Send requests to https://api.reelforger.com/v1/recipes/render.
Use canonical field recipe_id.
Keep style_preset at the root and recipe-specific values inside variables.

Variable behavior guide

background_audio_url: soundtrack that defines pacing budget.
items: ranked media entries shown in input order.
countdown_mode: label items as #N down to #1.
title_text / title_duration_seconds: dedicated intro heading.
hook_duration_seconds: reserve or skip opening hook time.

Payload and output preview

Payload example

{
  "recipe_id": "listicle_ranked",
  "style_preset": "bold_outline",
  "variables": {
    "background_audio_url": "https://pub-2ad5592bc4ca44abb609acfc0b7c5ceb.r2.dev/reel-forge-website-assets/porsche%20listicle%20music.mp3",
    "background_audio_start_seconds": 48,
    "background_audio_duration_seconds": 9,
    "hook_title": "Top 3 Porsche Details",
    "hook_duration_seconds": 0,
    "title_text": "Top 3 Porsche Details",
    "title_duration_seconds": 1.4,
    "countdown_mode": true,
    "item_title_style": {
      "color": "#FFFFFF",
      "font_size": 78,
      "font_weight": 900,
      "text_align": "center",
      "stroke_color": "rgba(0,0,0,0.92)",
      "stroke_width": 5
    },
    "items": [
      { "title": "Driver cockpit", "media_url": "https://pub-2ad5592bc4ca44abb609acfc0b7c5ceb.r2.dev/reel-forge-website-assets/porsche%20vid%202.mp4" },
      { "title": "Rear light signature", "media_url": "https://pub-2ad5592bc4ca44abb609acfc0b7c5ceb.r2.dev/reel-forge-website-assets/porsche%20rear%20lights%20clip.mp4" },
      { "title": "Turbo S stance", "media_url": "https://pub-2ad5592bc4ca44abb609acfc0b7c5ceb.r2.dev/reel-forge-website-assets/Porsche%20vid%201.mp4" }
    ]
  }
}

Output preview

Top 3 Porsche Details: 9s countdown with intro title, #3 -> #1 labels, and music trimmed from 48s.

Constraints

items must contain at least two entries
Total duration is capped at 60 seconds and derived from background audio timing
If hook_duration_seconds is > 0, hook and optional CTA consume item timing budget
countdown_mode labels follow item order as #N down to #1

Common mistakes and errors

Including rank prefixes inside item titles, which causes duplicate numbering
Forgetting to trim/cap long music with background_audio_start_seconds/background_audio_duration_seconds
Leaving hook_duration_seconds at default when you want items to begin immediately