ghcr.io/wei-shaw/sub2api:0.2.2

Sub2API

用于订阅配额分配的AI API网关平台

英文 | 中文 | 日本語

⚠️ 重要声明

使用本项目前请仔细阅读以下内容：

• 🚨 服务条款风险：使用本项目可能违反Anthropic及其他上游提供商的服务条款。使用前请仔细阅读相关提供商的用户协议；由此产生的所有风险由用户自行承担。
• ⚖️ 合规使用：仅在符合您所在国家或地区***的前提下使用本项目。严禁任何非法使用。
• 📖 免责声明：本项目仅用于技术学习和研究目的。作者对因使用本项目导致的账号封禁、服务中断、数据丢失或任何其他直接或间接损害不承担任何责任。
• 🚫 无商业授权：本项目开发者从未授权任何个人或组织基于本项目进行任何形式的商业运营。任何以本项目名义或基于本项目开展的商业活动均与本项目及其开发者无关，由此产生的一切纠纷、损失和***责任由开展该活动的一方自行承担。

❤️ 赞助商

希望出现在这里？

感谢CCTK.AI对本项目的赞助！CCTK.AI是一个专注于稳定性和成本效益的AI API网关，为Claude、OpenAI、Gemini等热门模型提供快速中继服务。它与Claude Code、Codex等主流编码工具无缝协作，以官方成本的一小部分提供相同的模型能力。通过此链接注册，获取更快、更稳定、更经济的AI API访问。

One API，聚合所有顶级模型！OpenModel是企业级高可用AI API网关，让您的应用真正实现快速稳定：自动故障转移、智能路由至性能最佳的通道，以及企业级SLA。其SLA远超任何单一提供商——让稳定性成为您的核心竞争优势。直接支持Claude Code、Codex和Gemini CLI。通过此链接注册开始使用。

感谢ETok.ai对本项目的赞助！ETok.ai致力于打造一站式AI编程工具服务平台。我们提供专业的Claude Code套餐和技术社区服务，并支持Google Gemini和OpenAI Codex。通过精心设计的方案和专业的技术社区，为开发者提供可靠的服务保障和持续的技术支持，让AI辅助编程成为真正的生产力工具。点击此处注册！

感谢APIKEY.FUN对本项目的赞助！APIKEY.FUN是sub2api开源项目的核心贡献者之一，致力于提供开放、稳定且经济的AI API访问。该平台支持Claude、OpenAI、Gemini等热门模型的API中继服务，价格低至原价的7%。通过专属链接注册：APIKEY，享受所有充值额外5%折扣。

感谢AIGoCode对本项目的赞助！AIGoCode是一个集成Claude Code、Codex和最新Gemini模型的一体化平台，为您提供稳定、高效且极具成本效益的AI编码服务。平台提供灵活的订阅计划、零账号封禁风险、无需***直接访问，以及闪电般的响应速度。AIGoCode为sub2api用户准备了特别福利：通过此链接注册，首次充值可获得额外10%的信用额度！

以OpenAI价格的3%提供真正的GPT-5.6系列——CodexEverywhere正在为全球开发者普及前沿模型的访问。我们秉持透明和诚信原则，模型质量经过社区数月的积极监督验证。支持和加密货币支付。在codex-everywhere.com开始20免费试用。

特别感谢BmoPlus对本项目的赞助！BmoPlus是专为重度AI用户和开发者打造的高度可靠AI账号提供商。他们提供稳定可用的*** Plus / *** Pro（全程质保）/ Claude Pro / Super Grok / Gemini Pro账号及官方充值服务。通过BmoPlus - Premium AI Accounts & Top-ups注册并下单，用户可享受官方GPT订阅价格10%的惊人折扣（9折优惠）。

感谢Bestproxy对本项目的赞助！Bestproxy提供高纯净度住宅IP，支持一账号一IP专用配置。通过结合真实家庭网络与指纹隔离，实现链路环境隔离，降低关联风控概率。

感谢PatewayAI对本项目的赞助！PatewayAI是为重度AI开发者打造的优质API中继服务，提供100%源自官方提供商的完整Claude和Codex系列，采用透明的token级计费。企业方案包括高并发支持、专属管理、合同及发票服务。立即注册获取3试用 credits，充值享受6折起优惠，推荐奖励最高150。

感谢PPToken.cc对本项目的赞助！PPToken.cc专注于GPT模型API中继服务，支持Codex、Claude Code、OpenAI兼容客户端及Gemini CLI集成。充值比例1:1（1元=1***credit）；GPT模型倍率低至0.16x，整体成本约为官方定价的2.2%，首token延迟约1秒——是寻求低成本、高速访问GPT模型能力的开发者理想选择。技术支持：7×24小时真人响应（无机器人），在群聊中@tech，10分钟内获得回复。赞助福利：前200名通过专属注册链接注册并输入优惠码SUB2API的用户，可领取免费Codex / Claude Code试用credits——无最低消费，无需绑卡。

感谢Veilx对本项目的赞助！Veilx CDN专为大规模AI API流量设计，深度优化OpenAI、Claude、Gemini的中继服务和调用链，适用于聊天、图像生成、嵌入和流式传输等场景——在高并发下实现更低延迟和更高稳定性。还提供中国三网优化回程线路，是全球AI中继平台、海外AI SaaS和跨境高并发部署的理想选择。

感谢RoxyBrowser对本项目的赞助！RoxyBrowser是Sub2API的完美搭档：内置原生Roxy AI Agent和高质量原生住宅IP，支持通过简单命令进行批量自动化，显著提升多账号管理的安全性和效率！点击此链接注册，领取免费住宅IP套餐及终身9折优惠。

感谢Aimzoon对本项目的赞助！Aimzoon提供稳定且经济高效的AI API访问服务，使开发者能够快速将热门AI服务接入Codex、Claude Code和Gemini CLI等编码工具。无需复杂配置——上手更快、调用更稳定、成本更低。目前推出包括Codex折扣费率和特惠定价在内的促销活动，注册即可获得免费试用额度，让AI编码融入您的日常工作流。点击此处注册试用！

Nagora是一款为开发者和团队打造的多模型AI API网关。通过单个账户和API密钥，您可以通过统一接口访问超过26种主流文本和图像模型。它兼容OpenAI、Anthropic和Gemini协议，并与Claude Code、Codex和Gemini CLI等开发工具无缝集成。该平台提供智能路由、自动故障转移、透明定价和统一账单，以及预算管理、速率限制和并发控制功能。这使得AI使用在个人开发、团队协作和生产环境中更加可靠和易于管理。无需修改现有应用程序，只需替换Base URL和API密钥，即可在短短一分钟内完成集成。

感谢七牛智能（Qiniu AI）对本项目的赞助！七牛智能是七牛云（02567.HK）旗下的企业级大模型MaaS平台，提供一站式访问全球150+主流模型，兼容全球主要模型提供商的协议，覆盖文本、图像、音频、视频和文件处理等全模态能力，服务超过169万家企业和开发者。七牛智能为Sub2API用户提供专属福利：通过此链接注册——企业用户可获得1200万免费tokens，开发者可获得300万免费tokens。

感谢FennoAI对本项目的赞助！FennoAI是面向企业研发团队和开发者的高稳定性、高性能API中继服务提供商，兼容OpenAI和Anthropic协议，并与Codex、Claude Code和OpenCode等主流AI编码工具无缝集成。该平台具备企业级稳定性，支持每日1000亿tokens的调用量，并支持国内外实体的企业间结算和发票开具，满足企业研发和采购需求。作为Sub2API用户的专属福利，通过专属链接订阅，只需1.99即可获得价值50的Coding Plan额度。同时提供推荐奖励：邀请好友购买可获得高达20%的佣金——邀请越多，收益越多。

感谢LanoX AI对本项目的赞助！LanoX AI为开发者、团队和企业提供稳定且经济高效的全球模型访问服务。🎁 新用户福利——领取数百万免费tokens，外加500+免费模型，轻松实现低成本测试、验证与部署 🧠 全球领先模型——GPT · Claude · Gemini · 通义千问（Qwen）· Grok... 🎬 多模态创作——Seedance 2.0 · GPT Image · Gemini Nano Banana 🛡️ 企业级可靠性——高可用性 💎 原生能力输出 💎 无智能降级 💎 无模型混用 💎 透明的使用与计费 💎 💰 更低API成本——顶级模型低至官方定价的10%，文档清晰、集成简单、支持开票，满足企业级批量使用需求 🏢 企业之选——适用于AI产品、智能体（Agents）、内容平台及高模型使用量的研发团队

生态系统

扩展或集成 Sub2API 的社区项目：

方法4：从源码构建

从源代码构建并运行，用于开发或自定义。

前提条件

• Go 1.21+
• Node.js 18+
• PostgreSQL 15+
• Redis 7+

构建步骤

# 1. 克隆仓库
git clone https://github.com/Wei-Shaw/sub2api.git
cd sub2api

# 2. 安装pnpm（如果尚未安装）
npm install -g pnpm

# 3. 构建前端
cd frontend
pnpm install
pnpm run build
# 输出将位于 ../backend/internal/web/dist/

# 4. 构建嵌入前端的后端
cd ../backend
VERSION="$(./scripts/resolve-version.sh)"
go build -tags embed -ldflags="-X main.Version=${VERSION}" -o sub2api ./cmd/server

# 5. 创建配置文件
cp ../deploy/config.example.yaml ./config.yaml

# 6. 编辑配置
nano config.yaml

[!NOTE] -tags embed 标志会将前端嵌入到二进制文件中。如果没有此标志，二进制文件将无法提供前端UI服务。

config.yaml 中的关键配置：

server:
host: "0.0.0.0"
port: 8080
mode: "release"

database:
host: "localhost"
port: 5432
user: "postgres"
password: "your_password"
dbname: "sub2api"

redis:
host: "localhost"
port: 6379
username: ""
password: ""

jwt:
secret: "change-this-to-a-secure-random-string"
expire_hour: 24

default:
user_concurrency: 5
user_balance: 0
api_key_prefix: "sk-"
rate_multiplier: 1.0

config.yaml 中还有其他与安全相关的选项：

• cors.allowed_origins 用于CORS允许列表
• security.url_allowlist 用于上游/定价/CRS主机允许列表
• security.url_allowlist.enabled 用于禁用URL验证（谨慎使用）
• security.url_allowlist.allow_insecure_http 用于在验证禁用时允许HTTP URL
• security.url_allowlist.allow_private_hosts 用于允许私有/本地IP地址
• security.response_headers.enabled 用于启用可配置的响应头过滤（禁用时使用默认允许列表）
• security.csp 用于控制Content-Security-Policy头
• billing.circuit_breaker 用于在计费错误时触发故障关闭
• security.trust_forwarded_ip_for_api_key_acl 启用旧版原始转发头接管（默认启用以确保升级兼容性）；禁用此选项可强制使用 server.trusted_proxies，其中应仅包含直接连接到Sub2API的精确代理CIDR
• security.forwarded_client_ip_headers 配置最多16个第三方CDN客户端IP头名称；仅在旧版接管启用时，会在检查内置头之前按顺序检查这些头

自定义客户端IP头可以在YAML中设置，或作为逗号分隔的环境变量设置：

SECURITY_FORWARDED_CLIENT_IP_HEADERS=True-Client-IP,X-CDN-Client-IP

头名称会经过验证、规范化和去重。管理员安全设置可以在不重启的情况下更新此列表；新安装会保留YAML/环境变量的默认值，现有安装会回填缺失的数据库值。禁用旧版接管时，所有自定义和内置的原始转发头都会被忽略，Gin仅使用 server.trusted_proxies。启用接管时，需将源站防火墙限制为CDN/代理地址，并让边缘节点覆盖所有受信任的客户端IP头。完整的迁移和信任边界规则请参见 deploy/EDGE_SECURITY.md。

[!WARNING] 安全警告：HTTP URL配置 当 security.url_allowlist.enabled=false 时，系统执行最小化的URL验证，并且默认允许HTTP URL（开发友好模式；Docker Compose部署使用相同默认值）。对于生产环境，需明确将其收紧为仅允许HTTPS：

> security:
> url_allowlist:
> enabled: false # 禁用允许列表检查
> allow_insecure_http: false # 仅允许HTTPS（生产环境推荐）
>

或通过环境变量：

> SECURITY_URL_ALLOWLIST_ENABLED=false
> SECURITY_URL_ALLOWLIST_ALLOW_INSECURE_HTTP=false
>

OpenAI Responses WebSocket 入口限制

gateway.openai_ws 限制面向客户端的 Responses WebSocket 会话的生命周期和总数量。这些防护措施独立于每轮用户和账户并发槽位（在轮次之间释放）生效。

gateway:
  openai_ws:
    # 接收并解压缩第一条客户端消息的总时间。
    client_first_message_timeout_seconds: 30
    # 关闭轮次完成后处于空闲状态的客户端 socket；0 禁用此防护。
    ingress_inter_turn_idle_timeout_seconds: 300
    # 基于 API 密钥的客户端入口会话分布式限制；0 禁用。
    max_ingress_connections_per_api_key: 64

首条消息超时是总读取截止时间。对于通过较慢链路接收大型上下文或图像密集型请求的部署，可以将其提高到 120-300 秒。该超时在 HTTP 桥接路由之前过期，因此桥接模式不会覆盖此限制。

连接上限通过 Redis 协调，使用 60 秒租约，每 20 秒刷新一次。若进程在整个租约期内无法确认租约，则会关闭其本地 WebSocket，而非在全局上限之外继续运行。

在选择账户级 WS 模式（如 http_bridge）之前，启用 v2 模式路由器：

gateway:
  openai_ws:
    mode_router_v2_enabled: true

或在环境中设置 GATEWAY_OPENAI_WS_MODE_ROUTER_V2_ENABLED=true。在部署或缓解上游 WebSocket 问题时，使用 http_bridge 进行客户端 WebSocket/上游 HTTP 操作。

强制 OpenAI 上游 HTTP/SSE

当出口代理或网络反复重连 OpenAI Responses WebSocket 时，在持久化部署配置中设置全局回退：

gateway:
  openai_ws:
    force_http: true

对于 Compose 和 Apple 容器部署，等效的 .env 设置为：

GATEWAY_OPENAI_WS_FORCE_HTTP=true

这会为原本使用 WebSocket 的 OpenAI 上游 Responses 流量选择 HTTP/SSE。它不会更改面向客户端的协议或强制使用 HTTP/1.1；当代理与 HTTP/2 不兼容时，需单独配置 gateway.openai_http2.enabled（或 GATEWAY_OPENAI_HTTP2_ENABLED=false）。与账户级 http_bridge 模式不同，此全局回退无需启用 mode_router_v2_enabled 即可生效。请将该设置保存在部署的持久化 .env 或 config.yaml 中，而非运行中的容器内，以便在镜像更新或容器重建后再次读取。

• 平台名称：grok
• 账户类型：OAuth 订阅账户和 xAI API-key 账户
• 公共 Responses 目标：/v1/responses、/responses 和 /backend-api/codex/responses，对于 OAuth 账户转发至 Grok 订阅代理，对于 API-key 账户转发至 https://api.x.ai/v1/responses
• 公共 Claude 兼容目标：/v1/messages，转换为 xAI Responses 并以 Anthropic Messages 输出形式返回，适用于 Claude CLI 风格客户端
• 公共 Chat Completions 目标：/v1/chat/completions 和 /chat/completions，转发至特定账户类型的 xAI 上游
• Codex CLI 风格的 Responses WebSocket 入口在 Responses 目标上被接受，并桥接至 xAI HTTP/SSE Responses 上游
• 文本模型：grok-4.5、grok-4.3、grok-build-0.1、grok-composer-2.5-fast、grok-4.20-0309-reasoning、grok-4.20-0309-non-reasoning 和 grok-4.20-multi-agent-0309
• Grok 群组的媒体目标：/v1/images/generations、/images/generations、/v1/images/edits、/images/edits、/v1/videos/generations、/videos/generations、/v1/videos/edits、/videos/edits、/v1/videos/extensions、/videos/extensions、/v1/videos/{request_id} 和 /videos/{request_id}。生成、编辑和扩展请求需要群组的 image-generation 权限。
• 媒体模型：grok-imagine、grok-imagine-image-quality、grok-imagine-image、grok-imagine-image-2.0、grok-imagine-edit、grok-imagine-video 和 grok-imagine-video-1.5
• JSON 图像编辑和视频生成请求接受 image、images、reference_images 和 mask 对象中的图像引用。对于 xAI 兼容的负载，使用 url；遗留的 image_url 字段仍被接受，并在转发前规范化为 url。
• 本提供程序不支持的范围：TTS、转录、浏览器自动化、Cookie 和 Grok 网络抓取

OAuth 配置

Grok OAuth 流程使用 PKCE，无需提交私有密钥。默认客户端详情遵循兼容客户端使用的公共 xAI OAuth 流程，所有值均可通过环境变量覆盖：

管理员可从仪表板创建 Grok OAuth 或 API-key 账户。OAuth 授权和重新授权也可通过管理员 API 进行：

OAuth 凭据存储复用现有的账户 JSON 字段：access_token、refresh_token、token_type、expires_at、base_url、可选的 email、可选的 subscription_tier 和 entitlement_status。OAuth 推理默认使用 https://cli-chat-proxy.grok.com/v1；存储旧默认值 https://api.x.ai/v1 的现有 OAuth 账户在运行时会重定向至订阅代理。显式自定义上游保持不变。

对于 API-key 账户，在创建账户对话框中选择 Grok → API Key。官方基础 URL 默认值为 https://api.x.ai/v1；凭据使用现有的 base_url 和 api_key 账户字段。OAuth 账户继续使用上述订阅流程。

Grok Build CLI 配置

1. 在 Sub2API 管理员仪表板中，添加 grok OAuth 账户并完成 xAI 授权，或添加 Grok API-key 账户。
2. 创建 Grok 群组，将账户附加到该群组，然后创建分配给该群组的 Sub2API API 密钥。
3. 在用户 API 密钥页面，点击 Use Key 并选择 Grok CLI。模态框会为 macOS/Linux 或 Windows 生成正确的文件和基础 URL。它还在 OpenCode 选项卡上提供 OpenCode 配置。
4. 如果手动配置，将以下内容保存为 ~/.grok/config.toml（Windows：%USERPROFILE%\.grok\config.toml）：

[models]
default = "grok"
web_search = "grok"

[model."grok"]
model = "grok-4.5"
base_url = "https://your-sub2api.example.com/v1"
name = "Grok 4.5"
api_key = "sk-your-sub2api-key"
api_backend = "responses"
context_window = 1000000
supports_backend_search = true

合并条目之前，请备份现有的 config.toml。该文件包含 Sub2API API 密钥，因此请将其保密并在支持的情况下限制其权限。验证有效配置并执行测试请求：

grok inspect
grok -p "Reply with sub2api-ok" -m grok

上述 base_url 是以 /v1 结尾的公共 Sub2API URL，而非 api.x.ai 或内部 xAI OAuth 代理 URL。

使用与配额显示

xAI 配额是被动的。Sub2API 不会虚构订阅配额值；当 xAI 发送成功或受速率限制的上游响应时，它会记录白名单中的 xAI 速率限制标头。在首次获得可用上游响应之前，仪表板会将配额显示为未知，但仍会显示本地 Sub2API 使用统计信息。

401 响应会暂时将凭据无效的账户从调度中移除。403 响应被视为访问或权限失败，而非令牌刷新循环。429 响应使用 Retry-After 或短暂冷却时间暂时将账户从调度中移除。

新的 Grok 图像和视频生成请求使用特定于媒体的资格检查。API-key 账户保持资格。具有明确 Free 或禁止计费证据的 OAuth 账户被排除在新媒体生成之外。在调度前会探测缺失或格式错误的观察结果；成功但不完整的计费响应被视为 billing_inconclusive 并保持资格以确保向后兼容性，因为未知的计费模式不能证明账户缺乏媒体权限。操作员可通过 extra.grok_media_eligible=false 隔离已知不良账户，或通过 true 强制启用已验证账户。导入会主动运行计费优先的配额探测。聊天请求和视频状态查询不受此仅媒体隔离的影响。如果没有剩余合格账户，媒体端点会返回 HTTP 503，错误类型为 grok_media_no_eligible_account。