*更新日期: 2026-11-07*

# 子账户

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

- 登录邮箱 + 密码（可登控制台，权限受限）
- 独立额度 `quota_balance`
- 一把专用 API Key（生成接口扣子账户额度）

当前基址：`https://tokenmei.com`。管理接口走 REST（OpenAI SDK **没有**对应方法），用 `fetch` / `curl` / `httpx` 即可。

| 角色 | Key | 能做什么 |
|------|-----|----------|
| 主账户 | 控制台创建、**未绑定**子账户的 `sk_live_…` | `/v1/sub-accounts` 全套管理；也可用该 Key 调生成和 `GET /v1/balance`（看主账户余额） |
| 子账户 | 创建时下发的 Key | [对话](/docs/chat) / [生图](/docs/images) / [生视频](/docs/videos) / [模型](/docs/models) / [任务](/docs/tasks) / `GET /v1/balance`；**不能**调管理接口 |

```http
Authorization: Bearer sk_live_MAIN_ACCOUNT_KEY
Content-Type: application/json
```

> **必须用主账户 Key 管理**
>
> 子账户 Key 调本页任一接口 → `403`，`code` 为 `management_forbidden`。请把「管理 Key」与「业务调用 Key」分开存放。

## 推荐流程

1. 用主账户 Key `POST /v1/sub-accounts` 创建（可顺带初始 `quota`）
2. 保存响应里的 `api_key_plaintext`（只出现一次）
3. 需要加额度时 `POST .../quota/allocate`；要收回时 `.../quota/reclaim`
4. 业务侧用**子账户 Key**调生成接口
5. 不用了再 `DELETE`（剩余额度自动回主账户）

## 钱包与金额

币种与计费约定见 [计费与产物](/docs/usage)。要点：

| 概念 | 说明 |
|------|------|
| 主账户余额 | 控制台总余额；划拨从此扣，收回加回 |
| `quota_balance` | 子账户可用额度；生成成功后扣这里 |
| 金额格式 | 划拨 / 收回 / 本页 `quota_balance` 是**十进制字符串**，最多 6 位小数。`GET /v1/balance` 另按两位小数向下取整，见 [计费与产物](/docs/usage)。不要用 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 | **仅创建响应**；明文，只一次 |

## 列表

**GET** `/v1/sub-accounts`

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

```json
{
  "object": "list",
  "data": [ /* 见对象字段 */ ]
}
```

```bash
curl https://tokenmei.com/v1/sub-accounts \
  -H "Authorization: Bearer $MOMO_API_KEY"
```

```javascript
const res = await fetch("https://tokenmei.com/v1/sub-accounts", {
  headers: { Authorization: \`Bearer \${process.env.MOMO_API_KEY}\` },
});
const body = await res.json();
console.log(body.data);
```

```python
import os, httpx
r = httpx.get(
    "https://tokenmei.com/v1/sub-accounts",
    headers={"Authorization": f"Bearer {os.environ['MOMO_API_KEY']}"},
)
print(r.json()["data"])
```

## 创建

**POST** `/v1/sub-accounts`

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `email` | string | 是 | 3–254；会转小写；全局唯一 |
| `password` | string | 是 | 8–128；子账户登录控制台用 |
| `quota` | string | 是 | 初始额度，可为 `"0"` |
| `display_name` | string | 否 | 1–64 |

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

请求：

```json
{
  "email": "team@example.com",
  "password": "at-least-8-chars",
  "quota": "10.00",
  "display_name": "Team A"
}
```

成功示例（字段值示意）：

```json
{
  "id": "clxsubaccount0001",
  "email": "team@example.com",
  "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_...."
}
```

```bash
curl https://tokenmei.com/v1/sub-accounts \
  -H "Authorization: Bearer $MOMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "team@example.com",
    "password": "at-least-8-chars",
    "quota": "10.00",
    "display_name": "Team A"
  }'
```

```javascript
const res = await fetch("https://tokenmei.com/v1/sub-accounts", {
  method: "POST",
  headers: {
    Authorization: \`Bearer \${process.env.MOMO_API_KEY}\`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    email: "team@example.com",
    password: "at-least-8-chars",
    quota: "10.00",
    display_name: "Team A",
  }),
});
const created = await res.json();
if (!res.ok) throw new Error(JSON.stringify(created));
console.log(created.id, created.api_key_plaintext);
```

```python
import os, httpx
r = httpx.post(
    "https://tokenmei.com/v1/sub-accounts",
    headers={"Authorization": f"Bearer {os.environ['MOMO_API_KEY']}"},
    json={
        "email": "team@example.com",
        "password": "at-least-8-chars",
        "quota": "10.00",
        "display_name": "Team A",
    },
)
r.raise_for_status()
created = r.json()
print(created["id"], created["api_key_plaintext"])
```

> **明文 Key 只返回一次**
>
> `api_key_plaintext` 不会再次下发。泄露后请到控制台「子账户」页轮换 Key（本 API 暂无 rotate）。

## 详情

**GET** `/v1/sub-accounts/{id}`

`{id}` 为创建返回的子账户 `id`。不存在或不属于本租户：`404`。

```bash
curl https://tokenmei.com/v1/sub-accounts/SUB_ACCOUNT_ID \
  -H "Authorization: Bearer $MOMO_API_KEY"
```

## 编辑

**PATCH** `/v1/sub-accounts/{id}`

字段均可选，至少传一项。密码留空表示不改。

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `display_name` | string | 否 | 最长 64；`""` 清空展示名 |
| `email` | string | 否 | 登录邮箱，全局唯一 |
| `password` | string | 否 | 新密码，至少 8 位 |

```json
{
  "display_name": "Renamed",
  "email": "ops@example.com",
  "password": "new-password"
}
```

成功返回更新后的子账户对象（不含 plaintext）。改邮箱后用新邮箱登录；改密码后旧密码立即失效。

```bash
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":"ops@example.com"}'
```

## 删除

**DELETE** `/v1/sub-accounts/{id}`

硬删用户：剩余 `quota_balance` **全部**收回主账户；Key 变为 `revoked` 并解绑。历史请求 / 任务仍挂在该 Key 上，便于审计。

```json
{ "reclaimed_amount": "3.500000" }
```

| 情况 | code | HTTP | 说明 |
|------|------|------|------|
| 有进行中扣费预留 | `usage_in_flight` | 409 | 等请求结束后再删 |
| 曾有兑换记录 | `has_redemptions` | 400 | 不可删 |
| 误传主账户自身 id | `cannot_delete_self` | 400 | 防护 |

```bash
curl -X DELETE https://tokenmei.com/v1/sub-accounts/SUB_ACCOUNT_ID \
  -H "Authorization: Bearer $MOMO_API_KEY"
```

```javascript
const res = await fetch("https://tokenmei.com/v1/sub-accounts/SUB_ACCOUNT_ID", {
  method: "DELETE",
  headers: { Authorization: \`Bearer \${process.env.MOMO_API_KEY}\` },
});
console.log(await res.json());
```

```python
import os, httpx
print(httpx.delete(
    "https://tokenmei.com/v1/sub-accounts/SUB_ACCOUNT_ID",
    headers={"Authorization": f"Bearer {os.environ['MOMO_API_KEY']}"},
).json())
```

## 额度划拨

**POST** `/v1/sub-accounts/{id}/quota/allocate`

主账户余额 → 子账户 `quota_balance`。

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `amount` | string | 是 | 必须大于 `"0"`，最多 6 位小数 |

主账户不足：`insufficient_balance`。成功返回更新后的子账户对象。

## 额度收回

**POST** `/v1/sub-accounts/{id}/quota/reclaim`

子账户 `quota_balance` → 主账户。请求体同划拨。子账户不足：`insufficient_quota`。

```bash
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"}'
```

```javascript
async function moveQuota(path, amount) {
  const res = await fetch(\`https://tokenmei.com/v1/sub-accounts/SUB_ACCOUNT_ID/quota/\${path}\`, {
    method: "POST",
    headers: {
      Authorization: \`Bearer \${process.env.MOMO_API_KEY}\`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ amount }),
  });
  return res.json();
}
console.log(await moveQuota("allocate", "5.00"));
console.log(await moveQuota("reclaim", "2.00"));
```

```python
import os, httpx
headers = {"Authorization": f"Bearer {os.environ['MOMO_API_KEY']}"}
base = "https://tokenmei.com/v1/sub-accounts/SUB_ACCOUNT_ID/quota"
print(httpx.post(f"{base}/allocate", headers=headers, json={"amount": "5.00"}).json())
print(httpx.post(f"{base}/reclaim", headers=headers, json={"amount": "2.00"}).json())
```

## 用子账户 Key 调生成

与主账户相同，只换 Bearer。额度耗尽后非 GET 返回 `429` + `insufficient_quota`；`GET /v1/models`、`GET /v1/balance`、`GET /v1/tasks/{id}` 仍可用。`GET /v1/balance` 此时返回该子账户额度（`scope` 为 `sub_account`）。详见 [鉴权与限流](/docs/authentication)。

```http
Authorization: Bearer sk_live_SUB_ACCOUNT_KEY
```

## 错误与限流

错误体外形与其它 `/v1` 一致，见 [错误码](/docs/errors)。业务看 `error.code`。

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

```json
{
  "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、启用/停用、流水 / 请求 / 任务分页。

相关文档：[鉴权与限流](/docs/authentication) · [计费与产物](/docs/usage) · [错误码](/docs/errors)
