API Key 额度与限制查询#

通过 API Key 额度与限制查询接口获取用于鉴权的当前 API Key 的可用额度、周期用量、模型白名单和 IP 地址白名单。该接口适用于服务启动前检查、调用前额度提示、预算监控和访问策略核对；不会返回同一账户下其他 API Key 的信息。

接口说明#

注意：/v1/api-key 是 API Key 管理专用接口，必须使用 https://unigateway.ai，不能使用常规的 https://api.unigateway.ai API 地址。

该接口不需要查询参数，只返回用于鉴权的 API Key 自身的信息。

准备工作#

请前往 UniGateway API Keys 创建或获取 API Key。请按业务要求配置 API Key 的访问控制、轮换和安全管理。

将 API Key 配置为服务端环境变量。不要将 API Key 写入浏览器前端代码、日志、公开仓库或监控上报内容：

export UNIGATEWAY_API_KEY="<YOUR_UNIGATEWAY_API_KEY>"

Windows PowerShell：

$env:UNIGATEWAY_API_KEY = "<YOUR_UNIGATEWAY_API_KEY>"

查询 API Key 额度与限制#

GET /v1/api-key

cURL 请求示例#

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

Python 请求示例#

以下示例使用 Python 标准库请求接口，并保留金额字段的原始十进制字符串：

import json
import os
from urllib.request import Request, urlopen

request = Request(
    "https://unigateway.ai/v1/api-key",
    headers={"Authorization": f"Bearer {os.environ['UNIGATEWAY_API_KEY']}"},
)
with urlopen(request, timeout=30) as response:
    result = json.load(response)

quota = result["quota"]
print("Available amount:", quota["available_amount"], quota["currency"])
print("Constrained by:", ", ".join(quota["constrained_by"]))
print("Allowed models:", result["restrictions"]["models"]["allowed"])

JavaScript 请求示例#

以下示例适用于 Node.js 18 或更高版本。不要在浏览器代码中使用该示例，因为 API Key 只能保存在服务端环境中。

const response = await fetch("https://unigateway.ai/v1/api-key", {
  headers: {
    Authorization: `Bearer ${process.env.UNIGATEWAY_API_KEY}`,
  },
});

if (!response.ok) {
  throw new Error(`API Key quota query failed: ${response.status} ${await response.text()}`);
}

const result = await response.json();
console.log("Available amount:", result.quota.available_amount, result.quota.currency);
console.log("Constrained by:", result.quota.constrained_by);
console.log("Allowed models:", result.restrictions.models.allowed);

响应#

{
  "api_key": {
    "name": "Production key",
    "last_used_at": "2026-07-21T03: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-22T00:00:00+08:00"
    },
    "weekly": {
      "limit": "100.000000000000",
      "used": "35.000000000000",
      "remaining": "65.000000000000",
      "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": ["claude-sonnet-5", "gpt-image-2"]
    },
    "ip_addresses": {
      "enabled": true,
      "allowed": ["203.0.113.10", "198.51.100.0/24"]
    }
  },
  "time_zone": "Asia/Shanghai"
}

顶层字段#

额度说明#

available_amount 表示当前 API Key 还能使用的计费额度，单位由 currency 指定。

对于预付费账户，接口会比较账户余额和所有已配置的 API Key 周期剩余额度，并返回其中最小值。API Key 未配置任何日、周、月限额时，available_amount 使用账户余额。

对于后付费账户：

• 未配置任何周期限额时，available_amount 为 null，is_unlimited 为 true。
• 配置了周期限额时，仍按已配置周期的最小剩余额度计算，is_unlimited 为 false。

后付费账户的 account_balance 是查询时的账户账务余额，不参与可用额度计算。is_unlimited 仅表示当前 API Key 没有金额上限，不代表模型权限、IP 地址限制或服务容量不受限制。

constrained_by 表示决定当前可用额度的限制来源，可能包含：

当多个限制的剩余额度相同时，constrained_by 会同时返回这些限制。

后付费账户示例#

下面的结果表示当前 API Key 没有配置日、周或月限额：

{
  "quota": {
    "currency": "USD",
    "billing_mode": "POSTPAID",
    "available_amount": null,
    "is_unlimited": true,
    "constrained_by": ["UNLIMITED"],
    "account_balance": "-12.500000000000"
  }
}

周期限额#

日、周、月周期均按响应中的 time_zone 计算：

• 日周期在当地时间每天 00:00 重置。
• 周周期在当地时间每周一 00:00 重置。
• 月周期在当地时间每月 1 日 00:00 重置。

某个周期的 limit 为 null 时，表示该周期不限制额度；对应的 remaining 也为 null，used 仍返回当前周期已经产生的计费金额。周期用量统计已完成计费或已获得部分可计费用量的记录，以查询时已经入账的数据为准。resets_at 是带时区偏移的 ISO-8601 时间。

模型与 IP 地址限制#

restrictions.models.enabled 为 false 且 allowed 为空时，表示 API Key 不限制 model；为 true 时，只能调用 allowed 中列出的 model。

restrictions.ip_addresses.enabled 为 false 且 allowed 为空时，表示 API Key 不限制 IP 地址访问；为 true 时，只接受 allowed 中列出的 IPv4、IPv6 地址或 CIDR 网段。

模型是否能够实际调用还可能受到模型服务状态和账户权限影响。建议仅在服务端短时缓存该响应，不要将其写入浏览器或长期持久化存储。

字段格式#

所有金额字段均以十进制字符串返回。处理金额时请使用高精度十进制类型，避免浮点精度误差。last_used_at 在 API Key 尚无调用记录时为 null。

错误处理与频率限制#

每个 API Key 的查询频率上限为每分钟 120 次。建议在服务端将查询结果缓存 1 分钟，避免将该接口置于每次模型调用的同步关键路径。

常见问题#

Q: 如何判断 API Key 是否配置了日、周、月限额、模型白名单或 IP 地址白名单？#

检查 limits.daily.limit、limits.weekly.limit 和 limits.monthly.limit：任一字段为 null 表示对应周期不限制额度。检查 restrictions.models：enabled 为 false 且 allowed 为空表示不限制 model。检查 restrictions.ip_addresses：enabled 为 false 且 allowed 为空表示不限制 IP 地址访问。配置发生变更后，重新请求 GET /v1/api-key 获取当前结果。

Q: 额度查询结果能否长期缓存？#

不建议长期缓存，但建议在服务端短时缓存 1 分钟。余额、周期用量、重置时间和白名单配置都可能变化；短时缓存可以降低轮询频率，且无需将该接口置于每次模型调用的同步路径。API Key 配置变更后，以及收到 401、403 或额度相关调用失败时，应立即使缓存失效并重新请求 GET /v1/api-key。不要在浏览器、日志或长期持久化存储中缓存该响应。