下载 Markdown

更新日期

子账户

把主账户余额拆成多个独立钱包,分给团队、客户或自动化任务。每个子账户有:

  • 登录邮箱 + 密码(可登控制台,权限受限)
  • 独立额度 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;不能调管理接口
http
Authorization: Bearer sk_live_MAIN_ACCOUNT_KEY
Content-Type: application/json

推荐流程

  1. 用主账户 Key POST /v1/sub-accounts 创建(可顺带初始 quota)
  2. 保存响应里的 api_key_plaintext(只出现一次)
  3. 需要加额度时 POST .../quota/allocate;要收回时 .../quota/reclaim
  4. 业务侧用子账户 Key调生成接口
  5. 不用了再 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。

字段类型说明
idstring子账户用户 id,即路径里的 {id}
emailstring登录邮箱,全局唯一;可通过 PATCH 修改
display_namestring | null展示名,最长 64
statusstringenabled / disabled(启停仅控制台)
quota_balancestring当前可用额度
total_chargestring该子账户 Key 历史计费合计
request_countnumber历史请求次数
api_keyobject | null当前绑定 Key 摘要;无 Key 为 null
api_key.idstringKey id
api_key.namestringKey 名称(默认取展示名或邮箱)
api_key.masked_keystring掩码 Key
api_key.statusstringactive / revoked
created_atstringISO 8601
api_key_plaintextstring仅创建响应;明文,只一次

列表

返回本租户全部子账户,无分页 query。

json
{
  "object": "list",
  "data": [ /* 见对象字段 */ ]
}
curl https://tokenmei.com/v1/sub-accounts \
-H "Authorization: Bearer $MOMO_API_KEY"

创建

字段类型必填说明
emailstring是3–254;会转小写;全局唯一
passwordstring是8–128;子账户登录控制台用
quotastring是初始额度,可为 "0"
display_namestring否1–64

每子账户最多一把 active Key,创建时自动签发。

请求:

json
{
  "email": "[email protected]",
  "password": "at-least-8-chars",
  "quota": "10.00",
  "display_name": "Team A"
}

成功示例(字段值示意):

json
{
  "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_namestring否最长 64;"" 清空展示名
emailstring否登录邮箱,全局唯一
passwordstring否新密码,至少 8 位
json
{
  "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 上,便于审计。

json
{ "reclaimed_amount": "3.500000" }
情况codeHTTP说明
有进行中扣费预留usage_in_flight409等请求结束后再删
曾有兑换记录has_redemptions400不可删
误传主账户自身 idcannot_delete_self400防护
curl -X DELETE https://tokenmei.com/v1/sub-accounts/SUB_ACCOUNT_ID \
-H "Authorization: Bearer $MOMO_API_KEY"

额度划拨

主账户余额 → 子账户 quota_balance。

字段类型必填说明
amountstring是必须大于 "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)。详见 鉴权与限流。

http
Authorization: Bearer sk_live_SUB_ACCOUNT_KEY

错误与限流

错误体外形与其它 /v1 一致,见 错误码。业务看 error.code。

子账户 Key 误调管理接口示例:

json
{
  "error": {
    "message": "子账户 API Key 不能执行管理操作,请使用主账户 API Key",
    "type": "invalid_request_error",
    "param": null,
    "code": "management_forbidden"
  }
}
codeHTTP何时
invalid_api_key401缺/错/吊销 Key;或子账户已停用却调生成
management_forbidden403子账户 Key 调管理;或主账户用户不可用
invalid_request400体校验失败(缺字段、金额格式等)
invalid_amount400金额解析失败或划拨/收回 ≤ 0
insufficient_balance400主账户不够划拨/创建初始额度
insufficient_quota400管理面:子账户不够收回;生成面余额不足多为 429
email_taken409邮箱已被占用
usage_in_flight409删除时仍有预留
has_redemptions400有兑换记录不可删
cannot_delete_self400不能删当前操作者自身
rate_limit_exceeded429管理 RPM 超限

管理接口:Key × management × 自然分钟,默认 60 RPM,与 chat / image / video 分开。无 Retry-After,等下一自然分钟。

管理路径不走「主账户余额 ≤ 0 则拒绝所有非 GET」的全局门闸;划拨/创建仍由业务校验余额。

与控制台

控制台「子账户」页(Cookie)与本 API 语义一致。目前仅控制台:轮换 Key、启用/停用、流水 / 请求 / 任务分页。

相关文档:鉴权与限流 · 计费与产物 · 错误码

子账户 · MomoAI算力超市