Routing and fallbacks

Each model can have several endpoints. Zalmir keeps the ones that match your preferences and tries them in order. By default the lowest total price goes first, and endpoints without a known price go last.

zalmir/auto

"model": "zalmir/auto" considers every eligible model and picks by your provider preferences, then the lowest known price. It does not read your prompt.

Model lists

Send models instead of model to try several models in order.

curl "$BASE_URL/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "models": ["<first model id>", "<second model id>"],
    "messages": [{ "role": "user", "content": "Hello" }]
  }'

Variants

Suffix	Effect
`:nitro`	Sort by throughput.
`:floor`	Sort by price.
`:free`	Not available yet: `404 no_free_endpoints` or `503 free_serving_unavailable`.
`:online`	Not supported: `400 unsupported_model_variant`.

curl "$BASE_URL/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model id>:nitro",
    "messages": [{ "role": "user", "content": "Hello" }]
  }'

Provider preferences

Field	Effect
`order`	Providers to try first, in this order. Others follow.
`only` / `ignore`	Allow-list and deny-list of providers.
`allow_fallbacks`	`false` makes one attempt only.
`sort`	`price`, `throughput` or `latency`.
`max_price`	`prompt` and `completion` ceilings, in the same unit as `pricing` in the model's endpoints list. Endpoints above either ceiling, or without a price, are skipped.
`quantizations`	Only endpoints with one of these quantizations.
`require_parameters`	Only endpoints that list support for every parameter you send.
`data_collection`, `zdr`	Privacy filters, covered in the privacy guide.

Any other field is refused with 400 invalid_routing, never ignored. Privacy fields: Privacy controls.

curl "$BASE_URL/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model id>",
    "messages": [{ "role": "user", "content": "Hello" }],
    "provider": { "order": ["<provider name>"], "allow_fallbacks": false }
  }'

curl "$BASE_URL/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "zalmir/auto",
    "messages": [{ "role": "user", "content": "Hello" }],
    "provider": { "sort": "throughput", "max_price": { "prompt": "1", "completion": "2" } }
  }'

Fallbacks

If an endpoint fails before answering, Zalmir releases that attempt and tries the next one; you are charged only for the answer you receive. A failed signature check is final and does not fall back. When nothing matches your preferences you get 404 no_eligible_provider.

An Idempotency-Key cannot be combined with more than one attempt (400 idempotency_unsupported_for_fallback); set allow_fallbacks: false when you use one.

Account defaults

On your Account page you can set a default model, fallbacks on or off, data collection and zero data retention. A request can make these stricter but not looser: an account default of no fallbacks, deny data collection or ZDR always applies.