Image API stream:true returns 400: use async mode and events

Sume's POST /v1/images does not support streaming: every catalog row reports supports_streaming: false, and stream: true returns 400 streaming_not_supported. To get progress, submit with mode: "async" and read GET /v1/jobs/:id/events, or use a webhook for the final event.

The stream field is in the schema so that clients can start sending it without a code change when native streaming ships. Until then it is rejected at runtime.

Other fields that return 400

Sume rejects an unlisted field instead of dropping it silently, so a request never runs with settings you did not get.

The three waits

There are three ways to wait, and subscribe is not a progress stream. mode: "subscribe" is an alias of sync and gives you one bounded 30-second wait.

For a slow job, mode: "async" returns a 202 envelope and you read /events for the job's progress. For a server-to-server flow, mode: "webhook" with a webhook_url delivers the terminal event.

• Interactive UI: show a spinner, use async, poll status.
• Backend: use a webhook and verify its signature with a non-empty secret.
• Scripts: sync with a 30 second wait, and handle 202.

A minimal progress pattern

If your UI needs a progress signal, do not fake a stream. Submit with mode: "async", show the queued state from the envelope, and update on each poll of the status endpoint. When the job reaches a terminal state, switch to the result view. The events endpoint gives you the history of the job for logs or a detail panel.

Because the stream field exists in the schema, a client library may send it by default. Strip it from your request builder until Sume ships native streaming, so a flag from a shared SDK cannot turn into a failed call.

• Strip stream from request bodies.
• Use /events for audit logs, not for tokens.

Billing while you wait

A completed generation is billed in full and a failed or cancelled one is not charged, so waiting through events costs nothing extra. A client that disconnects early is billed as a failed generation, which means no charge. See the Image API docs and the jobs docs.

A closing check for teams moving from another image API: compare the parameter list you send today with the Image API docs line by line. Fields such as seed, output_compression and stream are common in other services, and each returns a clear error here rather than being ignored. That behavior is useful, since a request that runs is a request that did what you asked, but it means a ported client will fail fast the first time. Fix the request builder once, and the rest of the migration is routine.

When native streaming does ship, it will show up in the catalog as supports_streaming: true for the models that offer it. Read that flag at startup rather than assuming, and the same code will keep working across the change.