---
title: Channel groups
description: 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](/docs/models/hosted) 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`](/docs/models/pricing#list-models) lists the groups serving each model, and the [marketplace](/models) shows every group with its current multiplier. `creative-hosted` runs [hosted models](/docs/models/hosted) 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](/app/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.

```bash title="cURL"
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"}]}'
```

```python title="Python"
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://lovelyrouter.com/v1",
    api_key=os.environ["LOVELY_API_KEY"],
    default_headers={"x-lovely-group": "gpt-value"},
)
```

```js title="Node.js"
import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://lovelyrouter.com/v1',
  apiKey: process.env.LOVELY_API_KEY,
  defaultHeaders: { 'x-lovely-group': 'gpt-value' },
});
```

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](/app/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](/docs/models/rate-limits) 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](/docs/models/pricing#how-a-call-is-charged) shows the full calculation.