Music API metadata field: tag tracks by campaign, not sent to provider

What metadata is

The Music Router request accepts metadata, described in the docs along with mode, webhook_url and wait_timeout_seconds as behaving the way they do on Music 1.0. The metadata is stored on the job and is not sent to the provider.

That makes it a safe place for your own labels. It will not change the music, and it will not leak your internal names to a vendor.

What to put in it

Keep it small and structural. A label you can search on later is worth more than a long description.

A request

{
  "prompt": "Bright acoustic guitar, upbeat, 30 seconds",
  "metadata": {
    "campaign": "spring-launch",
    "scene": "hero-intro",
    "take": 3
  }
}

Rules of thumb

• Never put secrets or personal data in it; treat it as stored job data.
• Reuse the Idempotency-Key only for the same payload, metadata included. A different payload with the same key returns 409 idempotency_conflict.
• Use a new key when you change take, since that is a new generation.
• Read it back from the job when you reconcile spend against campaigns.

Auditing later

A tag only helps if you read it back. When you reconcile a month of generations, list jobs, group by metadata.campaign, and multiply by $0.125. The result is a per-campaign music spend without scraping your own logs.

Decide on key names once for the whole team, and document them next to the code that sets them.

Why it helps with cost

Each generation is $0.125, so ten takes of a theme is $1.25. Tagging by campaign lets you add that up per project later instead of guessing. See music generation costs for the broader view.