Music job metadata: stored on the Sume job, not sent to Lyria

Short answer

The optional metadata object on a Sume music request is caller data that Sume stores on the job. It is not sent to the provider, so it cannot steer the music and you do not need to keep it free of internal names. Its only job is to let you tell takes apart later.

That description comes from the Music 1.0 request-fields table, and the Music Router docs say the router body is the same, plus an optional model.

Why tag takes

Three scenes with three takes each is nine jobs that look alike. A few keys make them tellable apart: scene, take number, the brief version and your own ticket id.

Keep keys short and stable, and write the same keys on every request in a batch. The docs promise only that Sume stores it on the job, so keep your own table keyed by job id as the record that matters.

curl -X POST https://api.sume.com/v1/music-router/generate \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: score-s02-take3-v2" \
  -d '{
    "model": "sume/music-auto",
    "prompt": "Dry 1998-style trip hop, 88 BPM, F minor. Warm Rhodes, slow brushed kit, a tape-delayed guitar answer at 0:15. A 30-second track. Instrumental, no vocals.",
    "metadata": { "scene": "s02", "take": 3, "brief": "v2", "ticket": "VID-214" }
  }'

Pair it with the idempotency key

The Idempotency-Key in the example encodes the same scene, take and brief, so each take has its own stable key. The docs examples for music send this header.

Log the engine too

The router echoes the id you asked for in job.model and names the engine that ran in job.request.routed_model, for example lyria-3.5 when you sent sume/music-auto. Log the pair next to your tags, since sume/music-auto is a routable id and the engine is named separately.

Cost

Every Music Router model charges the fixed Music price per audio generation, per the docs, so nine takes cost nine times that price whatever the tags say.

Three things metadata is not

• Do not put secrets or customer data in metadata; treat it as a label.
• Do not expect it to change the music. The provider never sees it.
• Prompt exclusions still go in the prompt. negative_prompt is rejected.

A tagging scheme that stays readable

Pick the keys before the first request and write them down. A scheme that works for a small video project is four keys: scene for the cut the music belongs to, take as a number, brief as a version label for the prompt text, and ticket for your own tracker id. Changing the prompt wording bumps brief; asking again with the same wording bumps only take.

That split matters when you review. If take 2 of brief v2 sounds better than take 1 of brief v1, you want to know whether the prompt or luck changed the result, and the tags tell you without opening the prompt.

Keep values small and plain: strings and numbers, not nested documents. The object is yours, but it travels with every job read, so a short value is easier to scan in a list.

• Same keys on every request in a batch, so filters work.
• One brief label per prompt text; never reuse a label for edited wording.
• Keep the prompt itself in your own repository, not only on the job.