Channel groups
A channel group is the pool of capacity that serves a model, with its own price multiplier. Bind a key to a group or choose one per request, and see which group served each call.
A channel is a source of capacity for a model. A channel group is a set of channels that serve the same models under one price multiplier. Every call is served by exactly one group, and the response tells you which one.
You don't need to choose a group. Keys default to Auto, which sends each request to the best available group for its model. Choose a group when you want every call from a key to be served and billed the same way.
Available groups#
| Group id | Name | Serves | Multiplier |
|---|---|---|---|
claude-value | Claude · Value | Claude models | ×1.00 |
gpt-value | GPT · Value | GPT models | ×1.00 |
gemini-value | Gemini · Value | Gemini models | ×1.00 |
creative-hosted | Creative · Hosted | Hosted models on dedicated GPUs | ×1.00 |
claude-api | Claude · API | Claude models — opt-in | ×1.08 |
The three value groups pool capacity from several channels for throughput, and keep every conversation on one channel so its prompt cache stays warm. The groups field of GET /v1/models lists the groups serving each model, and the marketplace shows every group with its current multiplier. creative-hosted runs hosted models on dedicated GPUs: one channel per model, and the first request after an idle spell waits while the model wakes up.
claude-api is a Claude group with its own channel. It is opt-in: keys on Auto never use it, so it serves only keys bound to it and requests that name it in x-lovely-group. Failover stays inside it, like any chosen group.
Bind a key to a group#
When you create a key in API keys, pick a Channel group. Every request made with that key is served by that group, whatever the request says. The group is fixed for the life of the key: to change it, create a new key.
Keys created with Auto can choose a group per request.
Choose a group per request#
Send the x-lovely-group header with the group id. It works on every LLM endpoint and in every API format.
curl https://lovelyrouter.com/v1/chat/completions \
-H "Authorization: Bearer $LOVELY_API_KEY" \
-H "x-lovely-group: gpt-value" \
-H "content-type: application/json" \
-d '{"model": "gpt-6.1-sol", "messages": [{"role": "user", "content": "Hi"}]}'The Anthropic SDKs take the same default_headers / defaultHeaders option.
| Situation | Result |
|---|---|
| Key bound to a group | The header is ignored; the key's group wins. |
| Unknown group id | 400 with Unknown group '<id>'. |
| Group doesn't serve the model in your API format | 404 with Model '<id>' is not served in <format> format in group '<group>'. |
See which group served a call#
Every successful response carries two headers:
| Header | Example |
|---|---|
x-lovely-group | claude-value |
x-lovely-channel | Pooled%20capacity (the group's channel label, URL-encoded) |
Logs show the group for every call and can be filtered by it.
Failover stays in the group#
When a channel fails or is full, the gateway retries the request on another channel. If your key is bound to a group, or you sent x-lovely-group, every retry stays inside that group, so the price and the group never change behind your back. With Auto and no header, a retry may use any group that serves the model; the x-lovely-group header always reports the one that answered.
See Rate limits & failover for when retries happen.
Pricing per group#
A call is billed at the model's list price times the multiplier of the group that served it. Keys on Auto pay list price (every group they use is at ×1.00); claude-api is at ×1.08. Models & pricing shows the full calculation.