一个 API Key，统一调用大模型、生图和联网搜索

如果一个 AI 应用需要同时使用大模型、图片生成和联网搜索，通常需要准备多少个 API Key？

答案可能是三个，也可能是五个，甚至更多。

每个模型供应商都有自己的 Key，图片服务可能来自另一个平台，搜索和网页抓取又需要单独申请账号。随着项目和成员增加，密钥很快就会散落在环境变量、部署平台和本地配置中。

OctaFuse Gateway 想把这个过程简化成：一个 Gateway URL，一把用户 API Key。

用户 Key 与 Provider Key 分离

客户端使用的不是上游 Provider 的真实密钥，而是 OctaFuse 创建的用户 Key。真实的 Provider Key 被保存在 Gateway 中，并由路由系统负责选择。

这种分离首先解决了安全和维护问题。业务应用不再直接持有供应商密钥，某把上游 Key 需要轮换时，也不必重新修改所有客户端。

其次，它建立了统一的用户身份。团队可以为不同成员、项目或客户创建 User，再给 User 创建一把或多把 API Key，并设置预算和周期。

无论用户调用的是 Chat、图片生成还是联网工具，都可以进入同一套用量和成本记录。

OctaFuse 对每次请求区分供应成本、目录标准价和用户计费。模型通常按 Token 统计，图片支持 Token 与按生成数量两种模式，Agent Tools 则可以按次计费。

一个 Key 可以调用什么

模型调用支持 OpenAI、Anthropic 和 Gemini 风格接口。图片能力提供 /v1/images/generations 与图片编辑接口。

Agent 联网能力当前包括：

/v1/tools/web-search
/v1/tools/web-fetch
/v1/tools/web-deep-search

工具上游失败时不会扣除用户预算，调用记录也会进入统一日志。

当某个 Provider 发生限流、余额不足或者服务异常时，Gateway 可以结合路由优先级、Key 池、熔断状态和余量选择其他路径。客户端继续使用原来的用户 Key，不需要了解背后的切换过程。

快速部署并创建第一把用户 Key

先在本地启动：

bash 复制代码

git clone https://github.com/OctaFuse/octafuse-gateway.git
cd octafuse-gateway
npm install
npm run db:migrate
npm run dev:proxy

另开终端运行：

bash 复制代码

npm run dev:admin

打开 http://127.0.0.1:8789，使用本地默认账号 admin / admin 登录。然后按以下顺序配置：

添加 Provider 和真实上游 Key；
创建或导入 Model；
为 Model 创建 Route；
创建 User，并设置预算与周期；
在 User 下创建用户 API Key。

拿到用户 Key 后，可以先查询当前身份和预算：

bash 复制代码

curl http://127.0.0.1:8787/v1/me \
  -H "Authorization: Bearer sk-your-api-key"

然后调用模型：

bash 复制代码

curl http://127.0.0.1:8787/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"your-route-model","messages":[{"role":"user","content":"Hello"}]}'

如果已经配置图片路由，同一把 Key 还可以调用：

bash 复制代码

curl http://127.0.0.1:8787/v1/images/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-image-2","prompt":"a watercolor fox","size":"1024x1024"}'

上云或自托管

Cloudflare 是 OctaFuse 的默认部署路径：

bash 复制代码

npx wrangler login
npm run bootstrap:cloudflare

不希望依赖 Cloudflare 时，也可以通过 Docker 部署，并使用 PostgreSQL 或 MySQL。生产环境上线前，需要修改 Admin 密码、轮换 Master Key，并用部署平台的 Secret 管理 Provider Key。

统一 API Key 的意义，不只是少配置几个环境变量。它是在客户端和供应商之间建立了一层稳定边界，让 Provider、密钥、路由、预算和计费都可以独立演进。

完整配置步骤请查看：