更新日期
子账户
把主账户余额拆成多个独立钱包,分给团队、客户或自动化任务。每个子账户有:
- 登录邮箱 + 密码(可登控制台,权限受限)
- 独立额度
quota_balance - 一把专用 API Key(生成接口扣子账户额度)
当前基址:https://tokenmei.com。管理接口走 REST(OpenAI SDK 没有对应方法),用 fetch / curl / httpx 即可。
| 角色 | Key | 能做什么 |
|---|---|---|
| 主账户 | 控制台创建、未绑定子账户的 sk_live_… | /v1/sub-accounts 全套管理;也可用该 Key 调生成和 GET /v1/balance(看主账户余额) |
| 子账户 | 创建时下发的 Key | 对话 / 生图 / 生视频 / 模型 / 任务 / GET /v1/balance;不能调管理接口 |
Authorization: Bearer sk_live_MAIN_ACCOUNT_KEY
Content-Type: application/json推荐流程
- 用主账户 Key
POST /v1/sub-accounts创建(可顺带初始quota) - 保存响应里的
api_key_plaintext(只出现一次) - 需要加额度时
POST .../quota/allocate;要收回时.../quota/reclaim - 业务侧用子账户 Key调生成接口
- 不用了再
DELETE(剩余额度自动回主账户)
钱包与金额
币种与计费约定见 计费与产物。要点:
| 概念 | 说明 |
|---|---|
| 主账户余额 | 控制台总余额;划拨从此扣,收回加回 |
quota_balance | 子账户可用额度;生成成功后扣这里 |
| 金额格式 | 划拨 / 收回 / 本页 quota_balance 是十进制字符串,最多 6 位小数。GET /v1/balance 另按两位小数向下取整,见 计费与产物。不要用 JSON number / float 累加 |
创建 quota | 可为 "0";大于 0 时立刻从主账户划出 |
划拨/收回 amount | 必须 大于 "0" |
| 流水类型 | 划拨 quota_allocate;收回 quota_reclaim;子账户消耗 subaccount_usage(控制台可见) |
子账户被控制台 停用(status: disabled)后,其 Key 调 /v1 生成接口会 401 + invalid_api_key;主账户仍可对该 id 划拨/编辑/删除。
对象字段
列表项、详情、划拨/收回成功体同一形状;创建时额外多 api_key_plaintext。
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | 子账户用户 id,即路径里的 {id} |
email | string | 登录邮箱,全局唯一;可通过 PATCH 修改 |
display_name | string | null | 展示名,最长 64 |
status | string | enabled / disabled(启停仅控制台) |
quota_balance | string | 当前可用额度 |
total_charge | string | 该子账户 Key 历史计费合计 |
request_count | number | 历史请求次数 |
api_key | object | null | 当前绑定 Key 摘要;无 Key 为 null |
api_key.id | string | Key id |
api_key.name | string | Key 名称(默认取展示名或邮箱) |
api_key.masked_key | string | 掩码 Key |
api_key.status | string | active / revoked |
created_at | string | ISO 8601 |
api_key_plaintext | string | 仅创建响应;明文,只一次 |
列表
返回本租户全部子账户,无分页 query。
{
"object": "list",
"data": [ /* 见对象字段 */ ]
}curl https://tokenmei.com/v1/sub-accounts \
-H "Authorization: Bearer $MOMO_API_KEY"创建
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
email | string | 是 | 3–254;会转小写;全局唯一 |
password | string | 是 | 8–128;子账户登录控制台用 |
quota | string | 是 | 初始额度,可为 "0" |
display_name | string | 否 | 1–64 |
每子账户最多一把 active Key,创建时自动签发。
请求:
{
"email": "[email protected]",
"password": "at-least-8-chars",
"quota": "10.00",
"display_name": "Team A"
}成功示例(字段值示意):
{
"id": "clxsubaccount0001",
"email": "[email protected]",
"display_name": "Team A",
"status": "enabled",
"quota_balance": "10.000000",
"total_charge": "0",
"request_count": 0,
"api_key": {
"id": "clkkey0001",
"name": "Team A",
"masked_key": "sk_live_****wxyz",
"status": "active"
},
"created_at": "2026-10-07T04:00:00.000Z",
"api_key_plaintext": "sk_live_...."
}curl https://tokenmei.com/v1/sub-accounts \
-H "Authorization: Bearer $MOMO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"email": "[email protected]",
"password": "at-least-8-chars",
"quota": "10.00",
"display_name": "Team A"
}'详情
{id} 为创建返回的子账户 id。不存在或不属于本租户:404。
curl https://tokenmei.com/v1/sub-accounts/SUB_ACCOUNT_ID \
-H "Authorization: Bearer $MOMO_API_KEY"编辑
字段均可选,至少传一项。密码留空表示不改。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
display_name | string | 否 | 最长 64;"" 清空展示名 |
email | string | 否 | 登录邮箱,全局唯一 |
password | string | 否 | 新密码,至少 8 位 |
{
"display_name": "Renamed",
"email": "[email protected]",
"password": "new-password"
}成功返回更新后的子账户对象(不含 plaintext)。改邮箱后用新邮箱登录;改密码后旧密码立即失效。
curl -X PATCH https://tokenmei.com/v1/sub-accounts/SUB_ACCOUNT_ID \
-H "Authorization: Bearer $MOMO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"display_name":"Renamed","email":"[email protected]"}'删除
硬删用户:剩余 quota_balance 全部收回主账户;Key 变为 revoked 并解绑。历史请求 / 任务仍挂在该 Key 上,便于审计。
{ "reclaimed_amount": "3.500000" }| 情况 | code | HTTP | 说明 |
|---|---|---|---|
| 有进行中扣费预留 | usage_in_flight | 409 | 等请求结束后再删 |
| 曾有兑换记录 | has_redemptions | 400 | 不可删 |
| 误传主账户自身 id | cannot_delete_self | 400 | 防护 |
curl -X DELETE https://tokenmei.com/v1/sub-accounts/SUB_ACCOUNT_ID \
-H "Authorization: Bearer $MOMO_API_KEY"额度划拨
主账户余额 → 子账户 quota_balance。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
amount | string | 是 | 必须大于 "0",最多 6 位小数 |
主账户不足:insufficient_balance。成功返回更新后的子账户对象。
额度收回
子账户 quota_balance → 主账户。请求体同划拨。子账户不足:insufficient_quota。
curl https://tokenmei.com/v1/sub-accounts/SUB_ACCOUNT_ID/quota/allocate \
-H "Authorization: Bearer $MOMO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"amount":"5.00"}'
curl https://tokenmei.com/v1/sub-accounts/SUB_ACCOUNT_ID/quota/reclaim \
-H "Authorization: Bearer $MOMO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"amount":"2.00"}'用子账户 Key 调生成
与主账户相同,只换 Bearer。额度耗尽后非 GET 返回 429 + insufficient_quota;GET /v1/models、GET /v1/balance、GET /v1/tasks/{id} 仍可用。GET /v1/balance 此时返回该子账户额度(scope 为 sub_account)。详见 鉴权与限流。
Authorization: Bearer sk_live_SUB_ACCOUNT_KEY错误与限流
错误体外形与其它 /v1 一致,见 错误码。业务看 error.code。
子账户 Key 误调管理接口示例:
{
"error": {
"message": "子账户 API Key 不能执行管理操作,请使用主账户 API Key",
"type": "invalid_request_error",
"param": null,
"code": "management_forbidden"
}
}| code | HTTP | 何时 |
|---|---|---|
invalid_api_key | 401 | 缺/错/吊销 Key;或子账户已停用却调生成 |
management_forbidden | 403 | 子账户 Key 调管理;或主账户用户不可用 |
invalid_request | 400 | 体校验失败(缺字段、金额格式等) |
invalid_amount | 400 | 金额解析失败或划拨/收回 ≤ 0 |
insufficient_balance | 400 | 主账户不够划拨/创建初始额度 |
insufficient_quota | 400 | 管理面:子账户不够收回;生成面余额不足多为 429 |
email_taken | 409 | 邮箱已被占用 |
usage_in_flight | 409 | 删除时仍有预留 |
has_redemptions | 400 | 有兑换记录不可删 |
cannot_delete_self | 400 | 不能删当前操作者自身 |
rate_limit_exceeded | 429 | 管理 RPM 超限 |
管理接口:Key × management × 自然分钟,默认 60 RPM,与 chat / image / video 分开。无 Retry-After,等下一自然分钟。
管理路径不走「主账户余额 ≤ 0 则拒绝所有非 GET」的全局门闸;划拨/创建仍由业务校验余额。
与控制台
控制台「子账户」页(Cookie)与本 API 语义一致。目前仅控制台:轮换 Key、启用/停用、流水 / 请求 / 任务分页。