Image job metadata on Sume: stored on the job, not sent upstream

Both Image 1.0 and POST /v1/images take an optional metadata object described as caller metadata stored on the job and not sent to the provider. Put your own order or SKU reference there so you can match a finished job to your records.

From Sume's Image 1.0 and Image API docs, read 2026-09-30.

Where does metadata go?

It is stored on the job. It is not part of the prompt and is not forwarded to the model provider, so it will not change the image. Keep values to your own identifiers rather than secrets, since the docs do not describe how metadata is returned or protected beyond storage on the job.

How do I send it?

Add the object next to the prompt:

curl -X POST https://api.sume.com/v1/images \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-image-2.5",
    "prompt": "Catalog shot of a linen shirt",
    "mode": "async",
    "metadata": { "sku": "demo-001", "batch": "spring" }
  }'

How do I match a result back?

Poll GET /v1/jobs/{id}/status and fetch GET /v1/jobs/{id}/result for each job id you stored, or take the terminal event on a webhook. Pair the job id with your own row when you submit, since that is the reliable key.

Does it replace an idempotency key?

No. Idempotency keys guard retries after client timeouts; reuse one only for the same operation and payload. Metadata is only a label.

How do I check this myself?

Keep metadata small and boring: identifiers, not personal data. If you need a value in the image itself, put it in the prompt instead, because metadata never reaches the model. The linked docs pages and the catalog endpoint show the current values, and this post reflects them as of 2026-09-30.