分组、渠道与模型

分组是 Sub2API 最重要的配置边界：它同时连接用户权限、账号池、模型路由、订阅额度和计费倍率。

分组与账号是多对多

Group A ─┬─ Account 1
         ├─ Account 2
         └─ Account 3

Group B ─┬─ Account 2
         └─ Account 4

同一个账号可以加入多个分组，但每个分组可能有不同用户、倍率和模型规则。账号临时限流时，会同时影响所有引用它的分组。

创建分组时的基本字段

字段	建议
name	使用能表达平台和等级的稳定名称
platform	与主要账号平台一致
status	配置完成并测试后再 active
rate_multiplier	明确用户侧价格倍率
is_exclusive	是否必须显式授权用户
subscription_type	明确标准/订阅逻辑
daily/weekly/monthly limit	套餐窗口限制
default_validity_days	默认订阅有效期
rpm_limit	分组级请求速率上限

平台字段决定路由

分组 platform 不只是展示字段。Gateway route 会根据它决定 Handler 和协议转换：

• OpenAI/Grok 分组会优先使用 OpenAI Gateway。
• Gemini 分组会进入 Gemini 兼容逻辑。
• Antigravity 可使用普通或强制平台路由。
• Anthropic 分组可进一步选择原生、Bedrock 或 Vertex 类型账号。

不要把不同平台账号随意混入一个分组，除非该调度逻辑明确支持跨平台候选。

模型范围

模型可在多个位置被限制：

1. 分组 supported_model_scopes。
2. 分组展示模型列表。
3. 分组模型路由规则。
4. 账号模型白名单或映射。
5. 上游账号实时能力。
6. 请求类型门禁，例如图片或视频开关。

最终能否执行取这些规则的交集。

模型映射

模型映射常见形式：

客户端请求 claude-sonnet-4-5
       │
       ├─ 分组精确映射
       ├─ Claude 系列映射
       ├─ 账号 model_mapping
       └─ default_mapped_model
       ▼
上游模型 gpt-5.4 / gemini-... / vendor-specific-id

要区分三个名字：

• requested model：客户端传入。
• upstream model：真正发给上游。
• billing model：用于查价和记录费用。

三者不一定相同。映射时必须确认 billing model，否则可能出现请求成功但价格查找失败。

模型路由

分组可以把模型模式映射到优先账号 ID 列表。例如高成本模型只走特定账号，普通模型使用通用池。

路由账号仍需满足 active、schedulable、并发、限流和模型能力等检查。优先列表不是强制绕过健康检查。

Claude Code only 与 fallback

开启 claude_code_only 后，分组只接受符合检测规则的 Claude Code 请求。非 Claude Code 请求可以：

• 直接拒绝；或
• 路由到 fallback_group_id。

还可以为 invalid request 单独配置 fallback。fallback 分组必须存在、可用，并重新执行计费资格与权限检查。

OpenAI Messages dispatch

OpenAI 分组要接收 /v1/messages，通常需要开启 allow_messages_dispatch。还可以配置：

• require_oauth_only：只使用非 API Key 类型账号。
• require_privacy_set：只选择隐私设置成功的账号。
• messages_dispatch_model_config：Claude 模型到 GPT 模型的映射。
• default_mapped_model：没有命中精确规则时的默认模型。

如果分组只服务原生 Responses 客户端，不应无意开启 Messages dispatch。

图片与视频

分组可以分别控制：

• 图片生成。
• 批量图片生成。
• 图片 1K/2K/4K 价格。
• 批量任务折扣与冻结比例。
• 视频独立倍率。
• 480p/720p/1080p 价格。

图片和视频可能使用独立倍率；关闭 independent 时才共享普通分组倍率。

高峰倍率

高峰配置包含开始、结束时间和倍率。当前规则要求同一天内结束时间大于开始时间，不支持类似 22:00-02:00 的跨天窗口。

时区由服务配置决定。多实例时区不一致会造成同一请求在不同实例计算不同倍率。

渠道的职责

渠道主要面向用户展示：

• 支持平台和模型。
• 定价与计费模型来源。
• 可用状态和监控结果。
• 排序、说明和外部链接。

渠道可以让用户看到“可以买什么”，分组决定“请求实际上怎么路由和计费”。公开运营时应该定期核对两者，避免页面宣称的价格与实际分组倍率不一致。

推荐配置流程

1. 先创建 disabled 测试分组。
2. 选择唯一平台和明确账号类型。
3. 加入少量测试账号。
4. 配置 requested/upstream/billing model。
5. 创建管理员自己的测试 Key。
6. 验证模型列表、非流式、流式和费用。
7. 设置用户权限和订阅限制。
8. 启用分组，再创建渠道展示。

变更风险

以下修改应视为发布操作：

• 改 platform。
• 改默认模型或 billing model。
• 大批量替换账号。
• 改倍率和高峰窗口。
• 开启 fallback group。
• 开启图片、视频或 Messages dispatch。

变更后应观察无可用账号、模型 404、计费失败和用户费用分布。