账户管理 API#

使用管理 API Key 查询账户下的 API Key 列表、指定 API Key 的额度、限制和用量，以及账户范围的用量记录。管理 API Key 使用 mk- 前缀，只能调用本文所述的账户管理接口，不能调用模型接口。

接口说明#

账户管理接口不能使用常规模型 API 的 Base URL https://api.unigateway.ai。接口仅接受管理 API Key；使用 sk- 前缀的普通 API Key 时，服务端返回 401 Unauthorized。

准备工作#

普通 API Key 不能用于本文接口。请在 管理 API Key 控制台 创建管理 API Key；完整 Key 仅在创建时显示一次。管理 API Key 的访问控制、轮换和安全管理应遵循账户的安全策略。

将管理 API Key 保存为服务端环境变量。不要将其写入浏览器前端代码、日志、公开仓库或导出文件：

export UNIGATEWAY_MANAGEMENT_KEY="<your-management-api-key>"

Windows PowerShell：

$env:UNIGATEWAY_MANAGEMENT_KEY = "<your-management-api-key>"

安全提示：管理 API Key 可以读取账户下所有 API Key 的元数据和用量。泄露后应立即轮换。

查询账户 API Key 列表#

GET /v1/account/api-keys

查询参数#

请求示例#

curl -G https://unigateway.ai/v1/account/api-keys \
  -H "Authorization: Bearer $UNIGATEWAY_MANAGEMENT_KEY" \
  --data-urlencode "limit=50" \
  --data-urlencode "offset=0"

响应示例#

{
  "items": [
    {
      "id": "token_01J4Z5D4V3K1R2M7Q8N9P0A1B2",
      "name": "Production",
      "key_prefix": "sk-abcdef0",
      "status": "ACTIVE",
      "created_at": "2026-07-23T03:12:00.000Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0,
  "has_more": false
}

响应不会包含完整 API Key、Key Hash 或访问控制配置。

查询 API Key 详情#

GET /v1/account/api-keys/{id}

使用列表接口返回的 id。目标 API Key 必须属于管理 API Key 所在的账户。ID 不存在或不属于该账户时返回 404 Not Found。

curl https://unigateway.ai/v1/account/api-keys/token_01J4Z5D4V3K1R2M7Q8N9P0A1B2 \
  -H "Authorization: Bearer $UNIGATEWAY_MANAGEMENT_KEY"

响应包含 api_key、quota、limits、restrictions 和 time_zone。返回的是路径中目标 API Key 的信息，不是用于鉴权的管理 API Key。

{
  "api_key": {
    "name": "Production",
    "last_used_at": "2026-07-23T03:12:00.000Z"
  },
  "quota": {
    "currency": "USD",
    "billing_mode": "PREPAID",
    "available_amount": "12.340000000000",
    "is_unlimited": false,
    "constrained_by": ["DAILY_LIMIT"],
    "account_balance": "50.000000000000"
  },
  "limits": {
    "daily": {
      "limit": "20.000000000000",
      "used": "7.660000000000",
      "remaining": "12.340000000000",
      "resets_at": "2026-07-24T00:00:00+08:00"
    },
    "weekly": {
      "limit": null,
      "used": "35.000000000000",
      "remaining": null,
      "resets_at": "2026-07-27T00:00:00+08:00"
    },
    "monthly": {
      "limit": null,
      "used": "80.000000000000",
      "remaining": null,
      "resets_at": "2026-08-01T00:00:00+08:00"
    }
  },
  "restrictions": {
    "models": {
      "enabled": true,
      "allowed": ["model-id-example"]
    },
    "ip_addresses": {
      "enabled": true,
      "allowed": ["203.0.113.10", "198.51.100.0/24"]
    }
  },
  "time_zone": "Asia/Shanghai"
}

详情响应字段#

金额均为十进制字符串。处理金额时请使用十进制定点类型，不要使用二进制浮点数。

查询单个 API Key 用量#

GET /v1/account/api-keys/{id}/usage

该接口返回路径中 {id} 对应 API Key 的用量记录。

用量查询参数#

from 与 to 例如 2026-07-01T00:00:00Z。时间范围兼容 start_date / end_date 和 startDate / endDate；新接入优先使用 from 与 to。

curl -G https://unigateway.ai/v1/account/api-keys/token_01J4Z5D4V3K1R2M7Q8N9P0A1B2/usage \
  -H "Authorization: Bearer $UNIGATEWAY_MANAGEMENT_KEY" \
  --data-urlencode "limit=100" \
  --data-urlencode "from=2026-07-01T00:00:00Z" \
  --data-urlencode "to=2026-07-31T23:59:59Z" \
  --data-urlencode "status=SUCCESS"

不要在该接口传入 token_id。目标 Key 已由路径中的 {id} 指定，传入 token_id 会返回 400 Bad Request。

响应中的 items 只包含路径 {id} 对应 API Key 的记录。使用 cursor 分页时，必须保持筛选条件不变，并将上一页的 next_cursor 原样传入下一次请求。

查询账户用量#

GET /v1/account/usage

该接口返回账户下所有 API Key 的用量记录，支持上一节的全部查询参数，另支持可选的 token_id 过滤。

curl -G https://unigateway.ai/v1/account/usage \
  -H "Authorization: Bearer $UNIGATEWAY_MANAGEMENT_KEY" \
  --data-urlencode "limit=100" \
  --data-urlencode "from=2026-07-01T00:00:00Z" \
  --data-urlencode "to=2026-07-31T23:59:59Z" \
  --data-urlencode "token_id=token_01J4Z5D4V3K1R2M7Q8N9P0A1B2"

省略 token_id 可查询整个账户的记录。使用 cursor 分页时，必须保持筛选条件不变，并将上一页的 next_cursor 原样传入下一次请求。

用量响应字段#

单 Key 用量和账户用量接口使用相同的响应结构。

不同 model 可能返回额外的用量或计费字段。客户端应读取当前响应实际返回的字段；金额字段仍应按十进制字符串处理。

分页#

用量接口支持 offset 和 cursor 两种分页模式。连续拉取、自动化导出和大范围查询应优先使用 cursor。

两种模式不能混用：使用 cursor 时，必须省略 offset 或将其设为 0。不要解析、修改或将其他查询的 cursor 复用于当前查询。需要恢复导出任务时，应保存最后成功页面的 next_cursor 和完整筛选条件。

验证用例#

运行单 Key 用例前，先设置列表接口返回的 API Key ID：

export API_KEY_ID="<api-key-id>"

以下命令适用于 Bash 或兼容 shell。执行前确认 UNIGATEWAY_MANAGEMENT_KEY 和 API_KEY_ID 均已在当前服务端环境加载。

curl -sS -D /tmp/unigateway-headers -o /tmp/unigateway-body \
  -G https://unigateway.ai/v1/account/api-keys \
  -H "Authorization: Bearer $UNIGATEWAY_MANAGEMENT_KEY" \
  --data-urlencode "limit=1" \
  --data-urlencode "offset=0"

grep -i '^cache-control: no-store' /tmp/unigateway-headers

服务端应返回 200 OK，响应中应包含 items、total、limit、offset 和 has_more；

错误处理与频率限制#

所有响应，包括错误响应，均包含 Cache-Control: no-store。

单 Key 用量和账户用量接口共享每分钟 60 次的限流。用量导出应在服务端执行；大范围查询使用 cursor 分页。需要续传的任务应同时保存 next_cursor 和完整的查询条件。

常见问题#

Q: 使用管理 API Key 后仍返回 401 Unauthorized，如何处理？#

确认请求的 Base URL 精确为 https://unigateway.ai，并检查 Authorization 使用的是当前有效的 mk- 前缀管理 API Key，而非普通 sk- API Key。确认 UNIGATEWAY_MANAGEMENT_KEY 已加载到发起请求的服务端进程后，重启或重新加载该进程的配置，再重新执行列表接口请求。管理 API Key 不能调用模型接口。

Q: 查询单个 API Key 用量时为什么返回 400 Bad Request？#

检查请求 URL 是否包含 token_id。GET /v1/account/api-keys/{id}/usage 已通过路径中的 {id} 指定目标 API Key，必须移除 token_id 后重新请求。只有 GET /v1/account/usage 支持使用 token_id 按 API Key 过滤账户用量。

Q: 导出大量用量记录时如何避免重复或遗漏？#

首次请求不传 cursor，后续请求保留完全相同的 limit、时间范围和筛选条件，并传入上一页返回的 next_cursor。每次成功处理一页后持久化 next_cursor 与完整筛选条件；收到 429 Too Many Requests 时，降低并发并使用指数退避后从最后成功页面继续。cursor 不能用于其他筛选条件或其他 API Key 的查询。