Image API provider.only returns 400 provider_not_available on Sume

If you send provider: {"only": ["fal"]} to Sume's Image API you get 400 provider_not_available, because Sume publishes a single endpoint named sume for every catalog model. The routing fields exist in the schema so a client written for a multi-provider image router does not break, but only the slug sume is accepted in only and order.

Everything below comes from the Image API docs as of 2026-10-03. We are describing documented behaviour, not testing a live account.

Which routing fields does the Image API accept?

The request schema lists provider.only, provider.order, provider.ignore, provider.sort, provider.allow_fallbacks and provider.options. Their documented behaviour differs, and only two of them can change the outcome of a call.

Why is there only one endpoint?

The docs state that Sume serves every catalog model through a single sume endpoint in v1, so the model-level and endpoint-level supported_parameters are identical. Upstream provider identity is not disclosed. The per-endpoint record at GET /v1/images/models/{model_id}/endpoints therefore returns one entry, with provider_slug: "sume" and a pricing array of billable lines.

For a buyer this means price shopping across hosts is not a thing you do in the request. You choose the model, and the endpoint record tells you the billed amount per image. The cost_usd on a pricing line is already the amount charged to your wallet, with Sume's margin applied, so cost_usd times n is what a call costs.

How do you write a client that tolerates this?

The safest client does not send provider at all. If your code is shared with another router and must send it, pin only to ["sume"] and set allow_fallbacks to false, which is the exact example the docs give:

{
  "model": "bytedance-seed/seedream-4.5",
  "prompt": "a red panda astronaut floating in space",
  "provider": {
    "only": ["sume"],
    "allow_fallbacks": false
  }
}

What about provider.options and passthrough parameters?

provider.options is keyed by provider slug and is meant for vendor-only knobs. On Sume allowed_passthrough_parameters is an empty list for every endpoint in v1, so the field must be omitted or empty. A knob you may know from a vendor API, for instance a seed or an output-compression level, does not travel through it. The docs say seed and output_compression are in the schema but advertised by no model, so sending either returns 400 unsupported_parameter.

That is the same rule as for any other field: a request that sets a parameter the selected model does not list is rejected rather than silently dropped. Read supported_parameters first.

Is a 400 billed, and what should you check first?

The docs say image billing is all-or-nothing: a generation is either completed and billed in full, or it fails and is not billed. When you see provider_not_available, check three things in order: the provider object for any slug other than sume, the model id against GET /v1/images/models, and whether another layer in your stack is injecting a provider list on your behalf.

General error handling, including which statuses are worth retrying, is in Errors and credits. A 400 of this kind is not retryable unchanged.

A small guard in your own code saves the round trip. Before sending, strip or rewrite the provider object when the target is Sume, and log the model id and parameters you actually sent next to the request id you get back. If a shared SDK wrapper adds provider preferences for another router, the log line shows it immediately. Also keep the legacy route in mind: the older POST /v1/image-router/generate route still works but is deprecated in favour of /v1/images and will not gain new parameters, so new routing behaviour will only ever be documented on the Images API.