快速入门/账户与 API Keys

账户注册、API Key 创建、限额、模型与 IP 白名单、使用统计、安全实践、轮换与多密钥策略。

账户与 API Keys

本页说明如何注册和管理 UniGateway 账户、创建 API Key，以及配置 API Key 的限额、模型白名单、IP 白名单和使用统计、请求记录。

注册与登录

UniGateway 支持使用邮箱注册和登录。访问 UniGateway 登录页，完成注册或登录后即可进入控制台。

首次接入 API 前，请先创建至少一个 API Key。

账户级接口需要单独的管理 API Key。管理 API Key 的创建、一次性复制、配置和轮换方法请参阅管理 API Key。

API Key 管理

创建 API Key

按以下步骤创建 API Key：

  1. 登录并进入 UniGateway Dashboard。
  2. 在左侧导航栏点击 API Key。
  3. 在 API Key 页面右上角点击 新建 API Key。
  4. 填写 API Key 名称。名称用于区分不同环境、应用或服务，例如 production-chat 或 staging-rag；描述、日限额、周限额和月限额可按需要配置。
  5. 可选配置模型白名单，仅允许该 API Key 调用指定模型。
  6. 可选配置 IP 白名单。每行填写一个 IP 或 CIDR 网段，仅允许匹配的客户端出口 IP 发起请求。
  7. 完成配置后，滚动至页面底部并点击 创建 API Key。
  8. 创建成功后，立即保存完整密钥值。

完整密钥仅在创建时显示一次。若未保存或密钥丢失，请删除原密钥并创建新密钥；系统无法再次展示原始密钥内容。

验证 API Key

创建后，可以请求 https://api.unigateway.ai/v1/models 验证 API Key 是否可用。

Example request

Run it in your stack

Pick the SDK style that matches your app and copy the snippet directly into your project.

from openai import OpenAI

client = OpenAI(
  api_key="<YOUR_UNIGATEWAY_API_KEY>",
  base_url="https://api.unigateway.ai/v1",
)

resp = client.chat.completions.create(
  model="gpt-5.4",
  messages=[{"role": "user", "content": "Hello"}],
)

cURL

curl https://api.unigateway.ai/v1/models \
  -H "Authorization: Bearer $UNIGATEWAY_API_KEY"

OpenAI SDK

安装依赖：

pip install openai

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["UNIGATEWAY_API_KEY"],
    base_url="https://api.unigateway.ai/v1",
)

models = client.models.list()
for model in models.data:
    print(model.id)

成功返回模型列表表示密钥可用于对应的模型调用。模型 ID 的选择方法请参考快速开始。

使用付费模型前，通常需要先完成充值并确保账户余额充足。请参考套餐与定价。

停用与删除密钥

拥有 API Key 管理权限的用户，可以在 API Key 页面停用不再使用、存在风险或需要临时隔离的密钥。停用后，该密钥不能继续用于新的 API 请求。

确认密钥不再需要时，可以将其删除。删除操作不可恢复；请在删除前确认相关应用已切换到有效的新密钥。

API Key 配置与使用管理

拥有 API Key 管理权限的用户，可以集中管理 API Key 的访问范围、消费限额和使用情况。

API Key 限额

可为单个 API Key 配置以下可选消费限额，金额单位为 USD：

限额周期适用场景
日限额控制单日消耗，降低异常流量的影响
周限额管理短周期预算和阶段性测试成本
月限额控制长期预算与生产环境成本

任一周期的消费达到设定阈值时，系统会自动停用该 API Key；留空则不限制该周期的消费。建议根据环境和服务用途设置不同额度，例如为测试环境设置较低的日限额与周限额。

模型白名单

为 API Key 启用模型白名单后，该密钥仅能调用已选模型；不配置白名单时，该密钥可访问当前账户可用的所有模型。

可以通过模型名称、供应商或部署类型搜索模型，也可以按供应商、常用模型和可用模型列表进行选择。模型列表会随当前账户可用范围变化。

IP 白名单

为 API Key 配置 IP 白名单后，仅允许来自受信任客户端 IP 或 CIDR 网段的请求使用该密钥。每行填写一个 IP 或 CIDR 网段，不支持使用逗号分隔；系统会校验请求客户端 IP。留空则不限制 IP。

配置白名单前，请确认应用实际对外请求使用的出口 IP。使用云服务、NAT 网关或 CI 平台时，出口 IP 可能与本地开发环境不同。

使用统计与请求记录

在控制台中可以查看与 API Key 对应的使用统计和请求记录，包括：

  • 七日消费趋势，用于识别成本变化和异常波动。
  • 最近请求记录，用于排查调用失败、模型选择或流量异常。
  • API Key 维度的用量信息，用于区分不同环境、服务或团队成员的消耗。

有关汇总统计、按条件聚合、逐请求明细和异步任务日志的说明，请参阅使用统计、用量分析、用量明细和任务日志文档。

建议为生产、测试和各独立服务分别创建 API Key，以便统计数据具备清晰的归属和可操作性。

密钥安全

应该做

  • 将密钥存放在服务端环境变量或密钥管理服务中。
  • 为生产、测试等不同环境创建独立密钥。
  • 为每个应用、服务或团队成员创建独立密钥。
  • 定期轮换密钥，并在轮换后删除旧密钥。
  • 发现泄露风险时立即停用或删除密钥。

不应该做

  • 将密钥提交到代码仓库、日志或配置模板中。
  • 在前端 JavaScript、移动端应用或公开页面中嵌入密钥。
  • 让多个应用或团队成员长期共用同一密钥。
  • 通过聊天、邮件、Issue 或工单发送完整密钥。
  • 在怀疑密钥泄露后继续使用该密钥。

密钥轮换

需要零停机轮换密钥时，请按以下顺序操作：

  1. 在控制台创建新密钥。
  2. 将新密钥部署到应用的安全配置中。
  3. 使用新密钥验证 API 请求成功。
  4. 停用或删除旧密钥。

旧密钥在停用或删除前仍可使用，因此先完成验证再撤销旧密钥，可以避免业务请求中断。

多密钥策略

策略适用场景
每个环境一个密钥隔离测试与生产流量、限额和计费
每个服务一个密钥按微服务隔离用量、错误和访问策略
每位成员一个密钥审计个人 API 用量与访问行为
API Key 管理仅限管理员将密钥、限额和统计管理权限与日常模型调用职责隔离

修改密码

在控制台左侧导航栏点击 设置，即可进入密码修改页面。

常见问题

症状可能原因处理方式
每次请求返回 401 Unauthorized密钥缺失、无效或已被停用在控制台检查密钥状态；必要时创建新密钥并更新应用配置
有效密钥返回 403 Forbidden请求未满足模型或 IP 访问策略检查模型白名单、IP 白名单和所调用的接口
本地可用但 CI 环境不可用CI 未配置环境变量，或 CI 出口 IP 不在白名单中使用 CI 的密钥管理功能配置变量，并检查白名单规则
请求被限制已达到 API Key 的日、周或月限额在控制台检查该密钥的限额配置和当前用量
请求打到错误的上游base_url 设置不正确OpenAI SDK 使用 https://api.unigateway.ai/v1