Telluvian

Model Select

The engine behind Gallery. Send a prompt, get back the model that should answer it.

Copy this page as Markdown to paste into an AI assistant, or open it in one.

Model Select decides which model should answer a request. It reads the prompt, predicts how well each model in the model zoo will handle it, and returns the cheapest one expected to clear the quality bar set with xPerf, along with the reasoning effort to run it at.

There are two ways to use it:

  • Through Gallery. Set model to telluvian/gallery-1 and Gallery asks Model Select for a choice, sends your request to that model, and returns the answer. This is the usual route.
  • Directly, with POST /v1/modelSelect. You get the decision back and make the model call yourself. Use this when you call providers with your own keys, want to inspect or log the choice before acting on it, or want the decision without the generation.

Both take the same controls, make the same choice and cost the same.

The controls

Five optional controls shape the choice. On a direct call they sit beside messages. On a Gallery request they sit beside model, or, for tools that only let you set a model name, xPerf, xPerfEffort and xLatency can go in the model id itself. See controls in the model id.

ControlTypeDefault
xPerfnumber (0.8 and up recommended) or model id0.9
xPerfEffortstring, only with a model id in xPerfthe named model's best
xLatencyinstant, chat or batchchat
modelZoocomma-separated patternsthe whole model zoo
sessionIdGUIDa fresh one per request

Each is validated on its own. A bad value is a 400 naming the field, never a quiet fallback. See errors.

xPerf, the minimum quality bar

xPerf sets how good the answer needs to be, as a number or as a model id. Model Select sends each request to the cheapest model expected to reach that level of answer quality for that specific request. To be clear, this does allow a cheaper model to answer easy questions. A lot of models are 'frontier quality' when it comes to factual recall for example.

We recommend a number between 0.8 and the highest level in the model zoo, currently 1.14. The default is 0.9.

{"xPerf": 0.9}

A model id sets the bar at that model's general ability level, read as "at least as capable as this model". The request asks for that model's standard, not for that model, and usually gets something cheaper that meets the standard on the prompt.

{"xPerf": "anthropic/claude-sonnet-5-5"}

Choosing a value

  • 0.8 for routine work, where cost is the priority and nothing is too hard.
  • 0.9 (default): a compromise between cost and close to frontier quality.
  • 1.0 for close to the best possible top-end performance. Easy requests can still go to cheaper models.
  • Above 1.14, the highest level in the zoo: every request goes to the strongest model.

xPerf accepts values down to 0.1, but values below 0.8 let much weaker models answer, and we do not recommend them.

The scale

1.0 is defined as the general ability level of GPT-6 Astra, the model OpenAI launched in September 2026 as the start of what OpenAI called the "AGI era". The reference does not move, so an xPerf of 0.9 means the same next year as today. 1.0 is not a ceiling: a model stronger than GPT-6 Astra scores above 1.0.

Models on the scale

Each model in the model zoo has a general ability level: one number for the model's ability across a broad, hard benchmark. A model's actual performance varies from task to task, so Model Select estimates, for each prompt, how well every model in the zoo will answer. A cheap model can clear the xPerf on an easy prompt and fall short on a hard one, so the same xPerf can send two requests to different models. Model Select also counts estimated cache savings when comparing cost.

When the per-prompt estimate is unavailable, Model Select uses general ability levels alone and picks the cheapest model whose level is at or above the xPerf.

An xPerf no model can reach returns the strongest model, not an error

The request succeeds with the strongest model that fits the other controls, so an xPerf set too high shows up on the bill rather than as a 400. Check model on the response to see whether the xPerf is having an effect.

Send the number unquoted

"xPerf": "0.9" is a string, and strings are read as model ids. Shell quoting and String(x) in JavaScript are the usual causes. The request is rejected with a 400 suggesting the unquoted form.

xPerfEffort, which setting of that model you mean

Reasoning models are not one point on the scale. The same model at low and at max are far apart in both quality and price. When xPerf names such a model, xPerfEffort says which of its settings is the bar you mean:

{"xPerf": "openai/gpt-5.6-terra", "xPerfEffort": "low"}

Accepted values are minimal, low, medium, high, xhigh and max. Omit it and the named model is read at its best, which is what naming a model usually implies.

Models in the model zoo are measured at the single effort Model Select runs them at, so that is the only one they accept: {"xPerf": "openai/gpt-6.1-terra", "xPerfEffort": "high"} is a 400 naming max. Older models such as gpt-5.6-terra keep every published setting, as in the example above.

This sets the reference quality level, not a direct generation parameter. It only qualifies a named model. Sending it with a number is a 400 rather than being ignored, and so is asking for a setting that model does not offer. The error lists the ones it does.

xLatency, reserved

instant, chat (the default), and batch are accepted and recorded, but currently ignored during selection. They use the same model zoo and do not override xPerf, force a default model, promise latency, or enable provider batch pricing.

modelZoo, which models are allowed at all

A comma-separated list of glob patterns. Only models matching at least one pattern can be chosen. This is how you keep a request inside a provider you have a data agreement with, or out of one you do not:

{"modelZoo": "anthropic/*,openai/gpt-6*"}

Patterns match with or without the provider prefix and ignore case, so *mini* and openai/* are both valid. The patterns are matched against the model zoo, which GET /v1/modelSelect/models lists.

A pattern that matches nothing is an error

If no model in the zoo matches, the request fails with a 400. It does not fall back to the full list. A typo in an allowlist should not quietly widen it.

sessionId, keeping a conversation together

A GUID you resend on every turn of the same conversation:

{"sessionId": "3f2b7c58-9d41-4e0a-9a7c-6f0b1c2d3e4f"}

Multi-turn conversations are cheaper when consecutive turns land on the same model, because the history is already warm there. Passing a sessionId lets that weigh on the choice, so a conversation tends to stay put unless there is a real reason to move.

It is optional. Without one, every request is chosen on its own merits, which is right for one-shot work. A session is forgotten after an hour of inactivity.

Where the id comes from

Send none and Model Select issues one. A direct call always returns it, as does a non-streamed Gallery response. A Gallery stream does not, so for streaming, mint a GUID when a conversation starts, store it with the conversation, and send the same one each turn. A new id every turn is the same as sending none.

Calling it directly

POST /v1/modelSelect takes the conversation and the controls, and returns a decision. Nothing is generated.

curl https://api.telluvian.ai/v1/modelSelect \
  -H "Authorization: Bearer $TELLUVIAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "Summarise this changelog in one line: ..."}],
    "xPerf": "openai/gpt-6.1-terra"
  }'

This is not an OpenAI endpoint, so the OpenAI SDKs have no method for it. Call it with any HTTP client.

The request

FieldRule
messagesRequired. A string, treated as one user message, or an array of 1 to 2,000 messages whose last one has role user.
xPerf, xPerfEffort, xLatency, modelZoo, sessionIdOptional. See the controls.

Messages take roles system, user and assistant, with content as a string or an array of text and document parts. Any other field is rejected with a 400 rather than ignored, so a typo such as xPrf fails loudly instead of selecting at the default. The body can be at most 1 MB.

Not yet supported: tools and images

A tools field is a 400, and a message containing an image part is a 422. Document parts restrict the choice to models that accept documents.

The response

{
  "model": "claude-sonnet-5-5",
  "reasoning": { "effort": "max" },
  "sessionId": "3f2b7c58-9d41-4e0a-9a7c-6f0b1c2d3e4f",
  "cost": 0.0000015
}
FieldMeaning
modelThe chosen model's id, without a provider prefix.
reasoning{"effort": ...} to send to the model, or null when the model takes no reasoning effort.
sessionIdThe one you sent, or a newly issued GUID. Resend it next turn.
costWhat this call was billed, in USD. See what it costs.

The id names the model, not who hosts it. Send it as model to Telluvian's /v1/chat/completions as-is, or map it to your provider's name for that model. When reasoning is not null, pass its effort as the provider's reasoning effort parameter. When it is null, send none.

Errors

Errors from a direct call use their own envelope, with a stable code and the offending field:

{ "error": { "code": "out_of_range", "message": "xPerf must be at least 0.1.", "field": "xPerf" } }
StatuscodeWhen
400invalid_messagesmessages missing, empty or malformed, or the last message is not user.
400out_of_rangeNumeric xPerf below 0.1, a quoted number such as "0.9", or an unknown xLatency.
400unknown_modelxPerf names a model we do not know.
400invalid_effortxPerfEffort without a model-id xPerf, or an effort that model does not offer.
400empty_model_zoomodelZoo matches no model in the zoo.
400invalid_session_idsessionId is not a GUID.
400unknown_fieldA field not listed above.
413The body is over 1 MB.
422messages_too_largeNo model in the zoo has a context window that fits the messages.
422unsupported_inputNo model in the zoo accepts the messages' images or documents.
503Model Select is unavailable. Retry with backoff.

Authentication, credit and rate-limit errors are the same as on every other endpoint. See Errors.

What it costs

Model Select charges the Model Select fee, $0.05 per 1M input tokens, on the whole prompt. On a direct call the fee is the whole charge, recorded on your usage as modelSelect. Through Gallery the fee is added to the selected model's charge. A failed choice, a 400 or a 503, is not charged. See Pricing.