aimldocs
Guides

Routing hints in headers

Set the sort and a cost ceiling for one request from a client that cannot change the request body.

Most routing choices are made in the route object of the request body. A stock OpenAI or Anthropic client library can set request headers but cannot add fields to the body, so two hints are also accepted as headers. Every client library has a way to add default headers.

Sort

x-aiml-sort chooses how the hosts of a model are ordered for this request: price, latency, throughput, uptime, quality or weighted. If the body's route.sort is set, the body wins.

A cost ceiling for one request

x-aiml-max-cost-micro is the most this request may be projected to cost, in micro-USD (one millionth of a US dollar). The projection is the estimated input tokens plus the most output the request can produce (max_tokens when you set it), at the price of the host chosen to serve it.

A request projected above the ceiling is refused with status 400 and the code max_cost_exceeded before anything is reserved or sent to a provider. The message says what the projection was. Lower max_tokens, shorten the prompt or raise the ceiling.

The ceiling is a check before the request starts, not a meter during it. Budgets on the key, the project and the organization are what stop spending over time; see budgets.

Mistakes are refused

A header that is present but not valid, such as a sort that does not exist or a ceiling that is not a whole number above zero, is refused with schema_invalid naming the header. It is never ignored, so a ceiling you set is a ceiling you have.

Aliases: naming a kind of model

Besides model ids, the platform offers a few aliases, such as balanced. An alias names a kind of model, not one model: we point it at the model that best fits today, and may point it at another as prices and models change. The current list, with what each points at, is at GET /v1/aliases and needs no key.

With your own key for a provider on file, you can also name any model that provider serves as <provider>/<model>: the provider's id from the Own keys screen, a slash, and the provider's own model name, for example groq/llama-3.3-70b-versatile or together/meta-llama/Llama-3.3-70B-Instruct-Turbo. Such a request is served only through your key and charged the platform fee; see your own provider keys.

A request that names an alias is served by, and billed as, the model the alias points at when the request arrives. The response names that model and carries a model_alias warning, and the request log shows both. If you need one specific model to stay the same, name its id.

Routing policies and model changes

A routing policy can serve a request with a different model than the one asked for: a fallback model when nothing can serve the first, or a rule that sends some requests to another model. The response then names the model that served it, carries a policy_model or model_fallback warning, and is billed as that model.

On this page