model field and the
order you set is the order that gets tried.
What a profile is
- A name, which is for you. It is what you pick it out of a list by, and you can change it whenever you like.
- An identifier, which is what your code sends. See below for why it never changes.
- An ordered list of models: one primary, and up to four backups.
Requesting a profile
Putprofile/ and the identifier in the model field, exactly where a model
id would otherwise go:
Python
The identifier does not change
A profile’s name is yours to change at any time. Its identifier is not: once a profile is created, its identifier is fixed for the life of that profile. The reason is what each one is for. The name is how you find a profile in a list, and nothing downstream should care if you rename it as your own vocabulary changes. The identifier is what is already sitting in your code, in a CI config, in a teammate’s script you will never read. Ifprofile/nightly-batch
could be pointed at a different identifier later, the same three words your
code sends today could come to mean a different list of models tomorrow,
with nothing in your code telling you it happened. Fixing the identifier is
what keeps that from being possible: the name can move, so the meaning can be
kept current; the identifier cannot, so the meaning can be trusted.
Archiving a profile does not free its identifier, either. Once an identifier
has been used in a workspace, a new profile cannot claim it again.
What the order means
A profile’s models are tried strictly in the order you set. A request goes to the first model in the list. Only when that attempt answers with a status that means the model itself failed to serve it, rather than a fault in the request, does the request move on to the next model in your order, and so on. Any other failure, such as a malformed request, comes back to you as is: trying the same bad request against a different model would not fix it. A model in your list that cannot be served at all right now is skipped rather than counted as a failed attempt, as long as at least one model in the list still can be. Only when every model you named is unreachable does the request come back as a refusal, covered next.An archived or unknown identifier
Requestingprofile/<identifier> for a profile that has been archived, or one
that never existed, is refused identically either way: HTTP 503, code
no_provider_configured.
When no model in the profile can be served
A profile whose every member is out is refused rather than served, and the code says which kind of “out” it was. Every one of these names the profile slug you sent and no member of it: the list behind the slug is your own document, and your Profiles screen shows it in order.Limits
The fixed id unirouter/auto
unirouter/auto is one string you can put in a client’s configuration and leave
there. It names whichever of your routes you have made the default, so the route
behind it changes on the Routing screen without touching the code that calls us.
Once it resolves, everything after that is the ordinary route path: the same
order, the same failover, and the same charge for the step that answered.
Until you have a default route it still answers, from a list we publish for the
cost tier your workspace is on. There are three, low, balanced and
high, and a workspace that has never chosen is on balanced. The tier is a
shortlist and not a ceiling: low is cheaper because the models on it are
cheaper, and nothing about the tier limits what a request may spend. Setting a
default route of your own takes the id off our lists entirely, and yours answers
instead.
Two things it will not do. It never quietly serves you from a dearer tier than
the one you picked: if the tier you are on has no list, or nothing on it can be
served at that moment, the request is refused with 404
model_not_available and the message names your tier and both ways out. And it
never falls back to a tier or a route you did not choose, so a refusal here
means the same thing every time.
Which key a route runs on
A route can also say whose provider key its steps run on, which matters only if you have brought your own key for a provider we carry. The choice is per route and it has three values: follow your workspace’s own rule, which is what every route does unless you say otherwise; run on your own key; or run on ours. It is the way to keep one route off your own provider quota while the rest of your traffic stays on it. A step that cannot honour the choice is skipped, with the reason recorded, rather than served on the other key.Who can do what
Creating a profile, renaming it, replacing its model list, or archiving it all take the same permission: only the workspace owner and admins may do them. Any member of the workspace, including a developer or a viewer, may see the profiles that exist and request them, the same as any key in the workspace already can. See Workspaces and members for the full role table.Next
Models
How a model id is shaped, and how to discover which ones you can call.
Errors and refusals
The one error body the whole API uses, and how to read it.