Can I attach my order ID to an AI image job? Sume's metadata field

Yes. Sume's Image API request table lists metadata as an optional object of caller metadata that Sume stores on the job and does not send to the provider. Put your order id, customer reference or batch name there so the job can be traced back to your system.

Do not rely on it as your only record. Keep your own table keyed by the job id, because the docs describe what is stored and not how you read it back.

Three identifiers, three jobs

Submit and record

The script sends an async request with an order id, then writes the order and the job id to a small SQLite table. The Idempotency-Key is there so a retry of the same request does not become a second paid generation.

import os, sqlite3, requests

key = os.environ.get("SUME_API_KEY")
if not key:
    raise SystemExit("set SUME_API_KEY")
db = sqlite3.connect("orders.db")
db.execute("create table if not exists img (order_id text primary key, job_id text)")
order = "ord-1042"
r = requests.post(
    "https://api.sume.com/v1/images",
    headers={"Authorization": f"Bearer {key}", "Idempotency-Key": f"img-{order}"},
    json={"model": "ideogram/ideogram-v4.5", "quality": "low", "mode": "async",
          "prompt": "Gift tag, kraft paper, bold serif lettering",
          "metadata": {"order_id": order}},
    timeout=60,
)
r.raise_for_status()
job = r.json()["data"]["job"]["id"]
db.execute("insert or replace into img values (?, ?)", (order, job))
db.commit()
print(order, job)

What to keep out of metadata

• Anything secret. It is stored on the job, so treat it like job data.
• Large blobs. It is caller metadata, not a place for the source image.
• Personal data you do not need. An order number is enough to find the person in your own system.

Retry rules to keep

The jobs docs say not to submit the original paid request again just because a local process timed out. Poll the job first. If you must resend, reuse the same Idempotency-Key with the same payload. A changed payload is a different request and should get a new key.

Why the split matters

Because metadata is not sent to the provider, your order numbers and batch labels stay inside your Sume account and your own database. That is a useful default when the labels would mean something to a person who saw them.