渠道分组
Claude · Value、GPT · Value、Gemini · Value 三个分组分别汇聚各模型家族的容量，统一按官方标价五折计费。介绍如何按密钥或按请求选择分组。
Half Off Dev 上的每次调用都由三个渠道分组之一提供服务，每个模型家族对应一个分组。分组是一个容量池，由多个渠道（单个容量来源）组成，这些渠道以同一价格提供相同的模型。三个分组都按官方标价的一半计费，所以落到哪个分组都不影响你付多少钱。
大多数开发者根本不用碰这个设置。新建的密钥默认是 自动，会把每个请求发往服务该模型的分组。如果你想把某个密钥或某个请求明确固定到一个分组，或者想知道是哪个分组响应的，请往下看。
三个分组#
| 分组 ID | 名称 | 提供的模型 | 倍率 |
|---|---|---|---|
claude-value | Claude · Value | Claude 模型 | ×0.50 |
gpt-value | GPT · Value | GPT 模型 | ×0.50 |
gemini-value | Gemini · Value | Gemini 模型 | ×0.50 |
每个分组都汇聚了多个渠道来提升吞吐，并让每段对话始终留在同一个渠道上，使提示缓存在多轮之间保持有效（见提示缓存）。GET /v1/models 的 groups 字段标明了每个模型所属的分组，模型广场则列出所有分组及其当前倍率。
如何选择分组#
请求最终进入哪个分组，有三种情况：
| 配置 | 由哪个分组服务 |
|---|---|
| 密钥为 自动，未带请求头 | 服务所请求模型的那个分组。 |
密钥为 自动，带 x-halfoff-group 请求头 | 请求头中指定的分组。 |
| 密钥已绑定分组 | 始终是密钥绑定的分组，请求头会被忽略。 |
每个模型家族只有一个分组，所以「自动」本身就会选对。绑定分组的用处在于把密钥限定在一个模型家族，比如交给编程助手、只允许调用 Claude 的密钥：请求其他模型时会直接返回 404，而不会被处理。
绑定密钥#
在 API 密钥页面创建密钥时，把 渠道分组 设为三个分组之一。此后用该密钥发出的每个请求都进入这个分组，不管请求里怎么写。绑定之后不能修改；需要换分组时，请新建一个密钥。其他密钥设置见 API 密钥。
按请求指定分组#
使用「自动」密钥时，加上带分组 ID 的 x-halfoff-group 请求头即可。所有模型端点、三种 API 格式都支持。
curl https://halfoff.dev/v1/messages \
-H "x-api-key: $HALFOFF_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "x-halfoff-group: claude-value" \
-H "content-type: application/json" \
-d '{"model": "claude-haiku-5.5", "max_tokens": 256,
"messages": [{"role": "user", "content": "用葡萄牙语打个招呼。"}]}'OpenAI SDK 也支持同样的 default_headers / defaultHeaders 选项。
| 情况 | 结果 |
|---|---|
| 密钥已绑定分组 | 请求头被忽略，由密钥的分组服务。 |
| 分组 ID 不存在 | 400，消息为 Unknown group '<id>'。 |
该分组不以你的 API 格式提供该模型（例如用 gpt-value 调 Claude 模型） | 404，消息为 Model '<id>' is not served in <format> format in group '<group>'. |
查看由哪个分组响应#
成功的响应会带上两个响应头：
| 响应头 | 示例 |
|---|---|
x-halfoff-group | claude-value |
x-halfoff-channel | Pooled%20capacity（该分组的渠道标签，经过 URL 编码） |
日志也记录了每次调用的分组，并支持按分组筛选。
故障转移不出分组#
渠道出错或已满时，网关会换一个渠道重试。如果密钥已绑定分组，或者请求带了 x-halfoff-group，所有重试都留在该分组内，分组和价格都不会在你不知情时变化。使用「自动」时，重试会发往服务该模型的分组，x-halfoff-group 始终显示最终响应的那个。何时会重试，见速率限制与故障转移。
各分组的价格#
一次调用的费用 = 模型官方标价 × 响应分组的倍率。三个分组都是 ×0.50，所以不管由哪个分组服务，每次调用都按官方标价的一半计费。完整算法见模型与价格。