> ## Documentation Index
> Fetch the complete documentation index at: https://telluvian.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Gallery

> A router you call like a model. Send one model id and each request goes to the right model.

Source: https://telluvian.ai/docs/gallery

renamed, sed this file plus the cross-links in index, quickstart, models,

Picking a model should be a per-request decision that almost nobody makes.
Currently, it gets made once at integration time and then forgotten about until
you run out of credit or look at your AI spend. The result is a frontier model
answering questions like "what's 5 km in miles", and a small model failing the
question that needed the frontier one.

Gallery is our router. Set `model` to `telluvian/gallery-1` and each request
goes to the cheapest model that still clears a quality bar you set. The response
gives you the answer and reports which model actually ran.

```json
{
  "model": "telluvian/gallery-1",
  "messages": [{"role": "user", "content": "Reformat this address as JSON: ..."}],
  "include_scores": false
}
```

Everything else about the request is unchanged. Streaming, multi-turn messages
and the [Responses API](https://telluvian.ai/docs/responses.md) work exactly as they do when you name a
model yourself.

> **Gallery runs on Model Select**
>
> The choice itself is made by [Model Select](https://telluvian.ai/docs/model-select.md), which reads
> your prompt and predicts how well each model in the zoo will handle it. Gallery
> asks Model Select for a model, then sends your request there. If you would
> rather make the model call yourself, call Model Select directly.

> **Verification is opt-in**
>
> Gallery does not turn on verification. Set `include_scores: true` to add
> [verification](https://telluvian.ai/docs/include-scores.md).

## Sending a request

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

```python
# The Model Select controls must go through extra_body. The Python SDK
# validates arguments against the OpenAI schema and rejects unknown keyword
# arguments before sending.
response = client.chat.completions.create(
    model="telluvian/gallery-1",
    messages=[{"role": "user", "content": "Summarise this changelog in one line: ..."}],
    extra_body={"xPerf": "openai/gpt-6.1-terra", "include_scores": False},
)

print(response.model)   # the model that actually ran
```

```typescript
// Goes inline. The JS SDK forwards unknown top-level keys as-is.
const response = await client.chat.completions.create({
  model: 'telluvian/gallery-1',
  messages: [{ role: 'user', content: 'Summarise this changelog in one line: ...' }],
  xPerf: 'openai/gpt-6.1-terra',
  include_scores: false,
} as OpenAI.ChatCompletionCreateParamsNonStreaming & {
  xPerf: string;
  include_scores: boolean;
});

console.log(response.model);   // the model that actually ran
```

## Reading what ran

`telluvian/gallery-1` is not a model. It is resolved to a real one before your
request is sent anywhere, so the `model` field on the response, and on every
chunk of a stream, names the model that generated the text:

```json
{
  "id": "chatcmpl-...",
  "model": "google/gemini-3.8-flash",
  "sessionId": "3f2b7c58-9d41-4e0a-9a7c-6f0b1c2d3e4f",
  "choices": [ ... ]
}
```

Log `response.model` to track what generated each answer. Non-streamed
responses also carry the `sessionId` Model Select used. See
[keeping a conversation together](https://telluvian.ai/docs/model-select.md#sessionid-keeping-a-conversation-together).

> **The choice is made before the model is called**
>
> Nothing is decided mid-generation, so `stream: true` behaves normally: the
> same SSE chunks in the same order. The one difference you can measure is time
> to first byte, because choosing costs a round trip before your request leaves
> for the model.

## Steering the choice

Gallery accepts the [Model Select controls](https://telluvian.ai/docs/model-select.md#the-controls) on
the request body alongside `model`: `xPerf`, `xPerfEffort`, `xLatency`,
`modelZoo` and `sessionId`. Gallery reads the controls only when `model` is
`telluvian/gallery-1`, passes them to Model Select unchanged, and never forwards
them to the model.

### Controls in the model id

Some tools only let you set a model name: agent frameworks, chat UIs, and
config files that take a model string and nothing else. For those, put the
controls in the model id after a colon:

```text
telluvian/gallery-1:xPerf=0.9
telluvian/gallery-1:xPerf=0.9,xLatency=instant
telluvian/gallery-1:xPerf=anthropic/claude-sonnet-5-5,xPerfEffort=high
```

This is the same request as sending the controls on the body. Gallery routes
it, bills it and reports it the same way, and the response's `model` still
names the model that ran. It works on Chat Completions and the
[Responses API](https://telluvian.ai/docs/responses.md), and OpenAI-compatible clients pass the model
id through unchanged:

```python
# No extra_body needed: the controls travel in the model id.
response = client.chat.completions.create(
    model="telluvian/gallery-1:xPerf=0.9",
    messages=[{"role": "user", "content": "Summarise this changelog in one line: ..."}],
)

print(response.model)   # the model that actually ran
```

```typescript
const response = await client.chat.completions.create({
  model: 'telluvian/gallery-1:xPerf=0.9',
  messages: [{ role: 'user', content: 'Summarise this changelog in one line: ...' }],
});
```

```python
# The openai/ prefix tells LiteLLM to speak the OpenAI format to api_base.
# Everything after it is sent as the model id.
response = litellm.completion(
    model="openai/telluvian/gallery-1:xPerf=0.9",
    api_base="https://api.telluvian.ai/v1",
    api_key=os.environ["TELLUVIAN_API_KEY"],
    messages=[{"role": "user", "content": "Summarise this changelog in one line: ..."}],
)
```

The rules:

- **`xPerf`, `xPerfEffort` and `xLatency` can go in the model id.** Separate
  several with commas. `modelZoo` and `sessionId` stay on the body: `modelZoo`
  uses commas itself, and a `sessionId` changes with each conversation, which a
  configured model name cannot.
- **Names are case-insensitive.** `XPerf=0.9` works, and so do
  `xLatency=Instant` and `xPerfEffort=HIGH`.
- **A number in the model id is a number.** `xPerf=0.9` sets the quality bar to
  `0.9`, so the [quoting problem](https://telluvian.ai/docs/model-select.md#xperf-the-minimum-quality-bar)
  a JSON body can have does not arise. Anything else, such as
  `xPerf=anthropic/claude-sonnet-5-5`, is read as a model id.
- **Set each control in one place.** A control in both the model id and the
  body must have the same value in each. If the two differ, the request is a
  `400`.
- **Mistakes are a `400` before anything runs.** A misspelt or unsupported
  control, a control given twice, or a suffix that is not `key=value` is
  rejected with a message showing the expected format, and nothing is billed.
  A suffix on any model other than `telluvian/gallery-1` is an unknown model,
  so a `404`.

`GET /v1/models/{id}` accepts these ids too, for tools that check a model
exists before using it, and returns the Gallery entry under the id you asked
for. `GET /v1/models` lists only the plain `telluvian/gallery-1`.

## What it costs

A Gallery request costs the selected model's list price plus the Model Select
fee. Naming a model yourself skips Model Select and the fee. See
[Pricing](https://telluvian.ai/docs/pricing.md).

> **Your invoice names real models, never this id**
>
> `telluvian/gallery-1` has no token rate of its own and never appears as a line
> item. Model spend is recorded against the model that generated the tokens, so
> usage reporting keeps working without knowing that Gallery is in play. The
> Model Select fee is billed as part of that model's charge.

## When Gallery is unavailable

If Model Select cannot make the choice, the request fails with a `503` and
nothing is charged. It is never served by quietly substituting a model. A
Gallery request that silently became something else would be indistinguishable
from a working one, and you would find out from the bill.

One narrow substitution does happen. If the model chosen is not one the
catalogue can serve, the default model runs instead. The response names it like
any other.
