ReelForger LogoDocumentation
Sign inGet Started

Music API

Use the Music API when you want ReelForger to generate reusable background music before a render.

This is a separate asynchronous workflow from video rendering:

  1. submit a music generation request
  2. poll for completion
  3. receive 2 generated track URLs
  4. use one of those track URLs in a normal ReelForger render request

When to use this API

Use this path when:

  • You want ReelForger to generate music from a prompt instead of supplying your own audio URL.
  • You want a reusable audio asset before deciding which video render to build.
  • You want to compare the 2 returned tracks and choose the best fit for a later render.

Do not use this path when:

  • You already have your own music URL and just want to render a video.
  • You expect music generation to happen inline inside a single /v1/videos/render or /v1/recipes/render request.

Core behavior

  • Every successful request costs exactly 20 credits.
  • Every successful request always returns exactly 2 tracks.
  • The returned audio_url values behave like standard public audio assets in ReelForger manifests.
  • Music generation is asynchronous, so you must poll the job until it reaches a terminal status.
  • Like render requests, music generation requests can also include metadata, webhook_url, webhook_headers, webhook_secret, and idempotency_key.

Endpoints

POST https://api.reelforger.com/v1/music/generate

Create a new music generation job.

Required auth:

  • Authorization: Bearer <API_KEY>

Optional headers:

  • idempotency-key for safe retries and deduplication

Optional body fields for async orchestration:

  • idempotency_key as a payload-level dedupe key
  • metadata as flat key/value pairs echoed back in webhook events
  • webhook_url to receive async completion/failure callbacks
  • webhook_headers for custom outbound webhook headers
  • webhook_secret using the same request shape as render jobs

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

Retrieve the current state of a music generation job.

The response includes:

  • current status
  • billing_policy
  • credit_cost
  • tracks[] once generation is complete

Request model

Simple mode

Simple mode is the default. Provide a prompt and ReelForger generates 2 tracks.

{
  "prompt": "Cinematic lo-fi beat with a slow emotional build and no vocals",
  "custom_mode": false,
  "instrumental": true,
  "model": "V5",
  "idempotency_key": "music-gen-001",
  "metadata": {
    "make_scenario_id": "12345",
    "campaign": "spring_launch"
  },
  "webhook_url": "https://api.example.com/reelforger/webhooks",
  "webhook_headers": {
    "X-Environment": "production"
  }
}

Custom mode

Custom mode lets you provide stronger creative direction.

Rules:

  • style is required
  • title is required
  • if instrumental is false, prompt is required and treated as lyric/source text
  • if instrumental is true, prompt is optional
{
  "prompt": "",
  "custom_mode": true,
  "instrumental": true,
  "model": "V5",
  "style": "ambient, cinematic, warm synth, slow build",
  "title": "Night Drive Bloom",
  "negative_tags": "harsh drums, distortion, shouting"
}

End-to-end example

Step 1: Create a music generation job

curl -X POST "https://api.reelforger.com/v1/music/generate" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "idempotency-key: music-gen-001" \
  -d '{
    "prompt": "Cinematic lo-fi beat with a slow emotional build and no vocals",
    "custom_mode": false,
    "instrumental": true,
    "model": "V5",
    "metadata": {
      "make_scenario_id": "12345",
      "campaign": "spring_launch"
    },
    "webhook_url": "https://api.example.com/reelforger/webhooks",
    "webhook_headers": {
      "X-Environment": "production"
    }
  }'

Example response:

{
  "success": true,
  "data": {
    "job_id": "9e1d1a87-1c7c-4518-a7d6-b65e24f9e6af",
    "billing_policy": "flat_20_credits",
    "credit_cost": 20
  },
  "request_id": "req_abc123"
}

Step 2: Poll until completed

curl -X GET "https://api.reelforger.com/v1/music/jobs/9e1d1a87-1c7c-4518-a7d6-b65e24f9e6af" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

Completed example response:

{
  "success": true,
  "data": {
    "id": "9e1d1a87-1c7c-4518-a7d6-b65e24f9e6af",
    "status": "completed",
    "billing_policy": "flat_20_credits",
    "credit_cost": 20,
    "tracks": [
      {
        "id": "track-1",
        "audio_url": "https://assets.reelforger.com/music/night-drive-1.mp3",
        "title": "Night Drive Bloom 1",
        "duration": 87
      },
      {
        "id": "track-2",
        "audio_url": "https://assets.reelforger.com/music/night-drive-2.mp3",
        "title": "Night Drive Bloom 2",
        "duration": 91
      }
    ]
  },
  "request_id": "req_abc124"
}

Using a returned track in a render

Once complete, pick one of the returned tracks[].audio_url values and use it exactly like any other audio asset.

curl -X POST "https://api.reelforger.com/v1/videos/render" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -d '{
    "version": "v1",
    "output": { "width": 1080, "height": 1920, "fps": 30 },
    "assets": [
      { "id": "clip1", "type": "video", "url": "https://example.com/clip1.mp4" },
      { "id": "music1", "type": "audio", "url": "https://assets.reelforger.com/music/night-drive-1.mp3" }
    ],
    "composition": {
      "timeline": [
        {
          "id": "video-1",
          "type": "video",
          "asset_id": "clip1",
          "time": { "start_seconds": 0, "duration_seconds": 8 }
        },
        {
          "id": "audio-1",
          "type": "audio",
          "asset_id": "music1",
          "time": { "start_seconds": 0, "duration_seconds": 8 },
          "media_settings": { "volume": 0.35, "loop": true }
        }
      ]
    }
  }'

Status model

Music generation jobs use these states:

  • queued
  • processing
  • completed
  • failed

When the job is:

  • queued or processing: tracks will usually be empty
  • completed: tracks will contain 2 generated songs
  • failed: error_message will describe the failure

If you provide webhook_url, ReelForger can also notify you asynchronously with:

  • music.generation.completed
  • music.generation.failed

Cost and output summary

  • Cost per successful request: 20 credits
  • Output per successful request: 2 distinct tracks
  • Best practice: compare both returned songs, choose the better one, then use that audio_url in your render
ReelForger