Music API metadata field: tag a track job with your own ids

Music requests on Sume accept an optional metadata field. The Music 1.0 docs describe it as caller metadata stored on the job and not sent to the provider, and the Music Router takes the same body. So you can put your own ids in it (an order number, a scene id) and match a finished track to your records, with no prompt text spent on bookkeeping and nothing leaking to the music engine. The docs do not state a size limit or a shape for the object, so keep it small and test your payload.

What goes in metadata, and what stays out?

Put in: ids you need to join on, such as scene_id or campaign. Keep out: anything you would not want stored on a job record, such as personal data you do not need, and anything meant to steer the music, which belongs in prompt. Because the field is not sent to the provider, it cannot change the audio.

How do I get it back?

Read the job through the normal job endpoints, GET /v1/jobs/{id}/status and GET /v1/jobs/{id}/result (see Jobs and results). Check on your own account where metadata appears in the envelope for your integration rather than assuming a location; the docs page for music names the field on the request, not its position in the response.

Does it replace an idempotency key?

No. metadata is for your labels; the Idempotency-Key header is what makes a retried create safe. Send both: a key per intended track, and metadata that says which track that is.

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: scene-12-bed-v1" \
  -d '{
    "prompt": "Calm ambient pad, 70 BPM, A minor. Instrumental, no vocals.",
    "metadata": { "scene_id": "12", "take": 1 }
  }'