2026-09-29

Image API provider.only and provider.order: which slug works?

Sume's image API takes provider.only and provider.order but lists one endpoint per model, slug sume. Which routing fields do anything, and the 400 for the rest.

3 min readSume

All posts

You can send provider.only and provider.order to POST /v1/images, but only one value is accepted: "sume". Every model in Sume's catalog publishes a single endpoint, so there is no second provider to pick, and any other slug returns 400 provider_not_available. The routing fields exist in the schema, but in v1 they do not steer a request anywhere.

Facts are from Sume's Image API docs, read 2026-09-29, and from the constants in Sume's image API contract package.

Which provider routing fields change anything?

Read 2026-09-29. Behavior of the provider object on POST /v1/images, from the Image API docs.
Field	What it is meant to do	Behavior in v1
`provider.only`	Allow only the listed provider slugs	Accepts only `"sume"`; any other slug is `400 provider_not_available`
`provider.order`	Try providers in the listed order	Accepts only `"sume"`; any other slug is `400 provider_not_available`
`provider.ignore`	Exclude the listed provider slugs	Accepted, no effect
`provider.sort`	Sort by price, throughput or latency	Accepted, no effect
`provider.allow_fallbacks`	Stop after the primary provider if false	Accepted, no effect
`provider.options`	Provider-specific parameters, by slug	Omit it or send it empty; `allowed_passthrough_parameters` is empty for every endpoint

How do I see which provider slugs a model has?

Ask the catalog before you write routing code. GET /v1/images/models/{model_id}/endpoints returns the endpoint records for a model, each with a provider_slug and a provider_tag. In v1 every model returns one record, with slug sume. The same record carries the definitive supported_parameters for that endpoint and a pricing line, so it is the place to check a field before you send it.

curl "https://api.sume.com/v1/images/models/bytedance-seed/seedream-4.5/endpoints" \
  -H "Authorization: Bearer $SUME_API_KEY"

How do I pin a request to the only provider?

Send the slug from the endpoint record. This is the request the docs show, and it is the only pin that is accepted:

curl -X POST https://api.sume.com/v1/images \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bytedance-seed/seedream-4.5",
    "prompt": "a red panda astronaut floating in space",
    "provider": { "only": ["sume"], "allow_fallbacks": false }
  }'

Does the provider field choose the model family?

No. The model family comes from model. Use a catalog id such as bytedance-seed/seedream-4.5, or sume/auto to let Sume choose. With sume/auto, the family that served the request is never returned to you: it is not listed by GET /v1/images/models, and job.model stays sume/auto. Upstream provider identity is not disclosed for any model, so a provider slug is not a way to select or detect one.

What should client code do with these fields?

Leave provider out unless a gateway you already use always sends it. If it does, keep only and order to "sume" and treat 400 provider_not_available as a configuration error, not a retryable one. Do not build fallback logic on allow_fallbacks: it has no effect, and a failed generation is not billed..

Sources

Image API