Music Router image_url: public HTTPS only, and null to clear it

Short answer

image_url on a Sume music request must be a public HTTPS image URL. Sending null is allowed only to clear an image on a client that reuses request objects. Anything else, such as a private link or a plain HTTP address, is not a valid input.

The rule is in the Music 1.0 constraints, and the Music Router docs state that its body is the same as Music 1.0 plus an optional model.

What the image is for

The prompt is required and carries the brief; image_url is an optional extra input next to it. The router accepts it on the same body as Music 1.0.

When it helps and when it does not

Use an image when the picture already carries the mood you cannot put in words, for example a product still whose color palette and light should be echoed in the score. Skip it when the brief is concrete: tempo, key, instruments and an arc with one named moment are things the image cannot specify. Listen to the result either way.

The example from the docs pairs a short prompt with a moodboard image.

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: music-image-001" \
  -d '{
    "model": "sume/music-auto",
    "prompt": "Cinematic ambient underscore matching the mood of the reference still, instrumental only",
    "image_url": "https://example.com/moodboard.png"
  }'

The two traps

Two details are easy to miss. First, the image must be reachable by a public HTTPS fetch, so a still behind a login will not work. Second, if you build requests from a shared object in code, a leftover image_url from the last scene is carried into the next one. Set image_url to null to clear it deliberately rather than deleting the key and hoping.

Multi-scene projects

For a multi-scene video, the tradeoff is continuity versus contrast. The docs advise that when scenes in one project should contrast, change the broad genre family, the tempo by at least 12 BPM and the lead instrument. If the user wants one consistent score, keep continuity and pass the same accepted scene still each time.

Cost

Each generation is billed at the fixed Music price, whether or not an image is attached. There is no per-image add-on in the docs.

A small test to run before committing a score

Because there is no seed, the way to learn whether the still helps is to run the same prompt twice, once with image_url and once without it, and listen to both back to back. That is two generations at the fixed Music price. If you cannot hear a difference that matters for the picture, drop the image from the template and keep the request simpler.

Write down which still you used. A still that is replaced later changes the result even if the prompt is the same, so store the still URL with the job. The metadata field on the request is a good place for it, because Sume keeps it on the job and does not send it to the provider.

When the request fails on the image, check the URL first: open it in a private browser window. If it asks you to sign in, or returns something other than an image, it is not a public HTTPS image in the sense the docs mean.

• Run with and without the image, same prompt.
• Store the still URL in metadata.
• Test the URL in a signed-out browser before you send it.