创建 API Key | ToAPIs Documentation

POST

/api/v1/api-keys

国内用户请注意: 中国大陆用户请使用 https://api.toapis.cn 作为接口地址 (Base URL). 文档示例中的 https://api.toapis.com 请替换为 https://api.toapis.cn.

使用说明

创建一个新的模型 Key, 用于调用生成接口. 成功时返回 HTTP 201 和完整密钥: 密钥只在该响应中出现一次, 后续 GET 不再返回, 请立即保存. 新 Key 使用账户的基础分组, 不能指定分组, 跨分组重试或 Webhook 配置. 初始额度只是该 Key 的调用上限, 不会从账户余额中预扣.

金额字段只接受非负十进制字符串, 且必须能精确换算为内部使用的整数额度单位, 不会自动截断小数. 每个账户最多保留 10000 个未删除的 Key, 达到上限返回 409 (code=13004). 创建不是幂等操作: 响应丢失时先查询列表确认是否已创建成功, 不要直接重试; 已创建但未保存的密钥可以通过轮换重新获取.

鉴权

Authorizationstring请求头必填

系统访问令牌, 格式为 Bearer YOUR_SYSTEM_ACCESS_TOKEN. 不接受模型 Key, 无需 X-User-Id. 共用规则见接入方式.

请求参数

非空请求体要求 Content-Type: application/json, 最大 16384 字节. 顶层必须是 JSON 对象, 拒绝未知字段, 重复字段和查询参数. 写请求有 10 秒正文读取期限.

namestring请求体必填

名称, 去首尾空白后必填, 最多 50 UTF-8 字节.

expires_atstring | null请求体

未来的 RFC 3339 时间, 小数秒向上取整. null 或创建时省略表示永不过期; 更新时省略保持原值.

unlimitedboolean请求体默认值: false

默认 false, 不接受 null. true 时 remaining_credits 只能省略或为 null, 给出值返回 400.

remaining_creditsstring请求体默认值: 0

初始剩余额度, 单位 credits, 默认字符串 "0".

daily_limit_creditsstring | null请求体

每日限额, 单位 credits. null 或字符串 "0" 表示不限额.

monthly_limit_creditsstring | null请求体

每月限额, 单位 credits. null 或字符串 "0" 表示不限额.

model_limitsarray请求体默认值:

模型 ID 数组, 默认 []. 非空时启用模型限制, 去空白后单项非空且不含逗号, 按首次出现去重, 拼接后最多 1024 UTF-8 字节.

allow_ipsarray请求体默认值:

仅限制该 Key 的模型调用来源 IP. 字符串数组, 支持单个 IPv4/IPv6 地址; 去首尾空白, 统一格式并去重. [] 表示不限制, null 或非法地址返回 400. 不支持 CIDR, 主机名, 端口或 IPv6 zone.

请求示例

curl --request POST \
  --url 'https://api.toapis.com/api/v1/api-keys' \
  --header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"name": "Example Key", "expires_at": "2027-01-01T00:00:00Z", "unlimited": false, "remaining_credits": "500", "daily_limit_credits": null, "monthly_limit_credits": null, "model_limits": ["example-image-model"]}'

import requests

response = requests.post(
    "https://api.toapis.com/api/v1/api-keys",
    headers={"Authorization": "Bearer YOUR_SYSTEM_ACCESS_TOKEN"},
    json={'name': 'Example Key', 'expires_at': '2027-01-01T00:00:00Z', 'unlimited': False, 'remaining_credits': '500', 'daily_limit_credits': None, 'monthly_limit_credits': None, 'model_limits': ['example-image-model']},
    timeout=30,
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://api.toapis.com/api/v1/api-keys", {
  method: "POST",
  headers: { Authorization: "Bearer YOUR_SYSTEM_ACCESS_TOKEN", "Content-Type": "application/json" },
  body: JSON.stringify({"name": "Example Key", "expires_at": "2027-01-01T00:00:00Z", "unlimited": false, "remaining_credits": "500", "daily_limit_credits": null, "monthly_limit_credits": null, "model_limits": ["example-image-model"]}),
  signal: AbortSignal.timeout(30_000),
});
if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}
console.log(await response.json());

响应字段

示例使用虚构数据. Key 元数据字段见获取 API Key 详情, 通用响应和错误处理见接入方式.

data.keystring

完整密钥, 已包含 sk- 前缀, 只在本次创建或轮换响应中返回.

响应示例

{
  "code": 0,
  "message": "",
  "data": {
    "id": "43",
    "name": "Example Key",
    "key_hint": "****xyz9",
    "status": "enabled",
    "created_at": "2026-11-01T08:00:00Z",
    "expires_at": "2027-01-01T00:00:00Z",
    "unlimited": false,
    "remaining_credits": "500",
    "daily_limit_credits": null,
    "monthly_limit_credits": null,
    "key": "sk-example00000000000000000000000000000000000000xyz9",
    "model_limits": [
      "example-image-model"
    ],
    "allow_ips": []
  }
}