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

# 对外 API

AISAPI 提供与 OpenAI 兼容的 `/v1` 接口。对话、图像生成与视频生成共用同一把客户 API Key（`sk_live_...`），无需按模型切换 SDK 或鉴权方案。

**基址：** `https://tokenmei.com`  
所有生成类接口均位于 `/v1` 路径下。

> **与 OpenAI 官方 SDK 的兼容性**
>
> 将 `apiKey` 替换为平台下发的 `sk_live_...`，并将 `baseURL` 设为基址加 `/v1`。对话与图像生成可直接沿用官方 SDK；视频请以本文 REST 字段为准。请将 Key 保存在服务端，切勿嵌入浏览器或公开客户端。

## 能力与接口

| 能力 | 路径 | 调用形态 | 计费 |
|------|------|----------|------|
| 对话 | `POST /v1/chat/completions` | 同步 / SSE 流式 | 按实际消耗的 token（usage） |
| Responses | `POST /v1/responses` | 同步 / SSE 流式 | 与对话相同（chat 模型） |
| 图像生成 | `POST /v1/images/generations` | 默认同步；`async: true` 时异步 | 按实际返回张数 |
| 视频生成 | `POST /v1/videos` | 异步任务 | 成功后按秒计费 |
| 任务查询 | `GET /v1/tasks/{id}` | 轮询图像 / 视频任务 | 不计费 |
| 模型目录 | `GET /v1/models` | 同步 | 不计费 |
| 余额查询 | `GET /v1/balance` | 同步 | 不计费 |
| 子账户管理 | `/v1/sub-accounts` | 主账户 Key；见 [子账户](/docs/sub-accounts) | 划拨/收回额度，不按 token 计费 |

`GET /healthz` 无需鉴权，仅用于存活探测。

## 模型可见性与可调用性

`GET /v1/models` 仅返回同时满足以下条件的模型：

- 平台已开放
- 模型已启用
- 能力已实现（`chat` / `image` / `video`）

每条记录包含 `capability`、`display_name`，并可能包含 `features`、`limits` 与 `pricing`（对客售价）。可通过 `?capability=` 或 `?owned_by=` 过滤。

未上架、熔断中，以及 embedding、语音等仅目录能力不会出现在结果中。调用未列出的 id 将返回 `model_not_found`。即便未定价模型被误列入目录，调用仍返回 `model_not_found`。

Embedding、TTS、ASR 即使出现在运营目录中，对客调用亦返回 `capability_not_enabled`。

## 计费原则

仅在请求成功完成后扣减余额。失败、超时与内容策略拒绝不产生费用。

- **对话：** 流式结束后按实际消耗的 token（usage）结算
- **图像：** 按返回的 `data.length` 计费（至少按 1 张）
- **视频：** 上游生成成功并交付结果 URL 后，按秒计费（转存开启时在转存完成后交付）

余额为 0 时，新的生成类请求将被拒绝；`GET` 类接口（列模型、查任务、查余额）仍可用。`GET /v1/balance` 的返回值固定两位小数并向下取整，字段说明见 [计费与产物](/docs/usage)。

## 集成约束

- **产物 URL：** `response_format=url` 的图像与视频默认先转存至平台存储，再返回稳定地址；上架视频模型可关闭转存，此时视频地址由上游提供且可能过期。请勿持久化临时链接。
- **鉴权隔离：** 运营管理台 Cookie 与客户 `sk_` Key 完全分离。请勿使用管理台账号调用 `/v1`。
- **调用路径：** 客户集成须经由服务端发起。CORS 面向管理台配置；请勿从任意前端域名直连 API。
- **能力边界：** function calling 支持 `type: function` 的 `tools`（调用方执行函数，网关透传）。自动故障转移、以及 `web_search` 等内置工具不在范围内。Vision / 文件附件见 [对话](/docs/chat) / [Responses](/docs/responses)；无 `/v1/files`，`file_id` 会 400。

下一步：[快速开始](/docs/quickstart)，或参阅 [SDK 对照](/docs/sdk) 确认路径与字段是否支持。

---

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

# 快速开始

运营在管理台创建 Key 后，明文只出现一次。之后只能看到前缀（如 `sk_live_nEZk`）。先把 Key 放进环境变量，再改 SDK 的 `baseURL`。

当前基址：`https://tokenmei.com`。

## 1. 列模型

确认这把 Key 实际能看到哪些对外 id。不要使用目录外的名称；只用 `GET /v1/models` 返回的 id。

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

```javascript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.MOMO_API_KEY,
  baseURL: "https://tokenmei.com/v1",
});

const models = await client.models.list();
console.log(models.data.map((item) => item.id));
```

```python
from openai import OpenAI
import os

client = OpenAI(api_key=os.environ["MOMO_API_KEY"], base_url="https://tokenmei.com/v1")
print([m.id for m in client.models.list().data])
```

```go
client := openai.NewClient(
	option.WithAPIKey(os.Getenv("MOMO_API_KEY")),
	option.WithBaseURL("https://tokenmei.com/v1"),
)
models, _ := client.Models.List(context.TODO(), openai.ModelListParams{})
for _, item := range models.Data {
	fmt.Println(item.ID)
}
```

```php
$client = OpenAI::factory()
    ->withApiKey(getenv("MOMO_API_KEY"))
    ->withBaseUri("https://tokenmei.com/v1")
    ->make();
foreach ($client->models()->list()->data as $item) {
    echo $item->id, PHP_EOL;
}
```

```java
OpenAIClient client = OpenAIOkHttpClient.builder()
    .apiKey(System.getenv("MOMO_API_KEY"))
    .baseUrl("https://tokenmei.com/v1")
    .build();
for (Model item : client.models().list().data()) {
    System.out.println(item.id());
}
```

```csharp
var client = new OpenAIClient(
    new ApiKeyCredential(Environment.GetEnvironmentVariable("MOMO_API_KEY")),
    new OpenAIClientOptions { Endpoint = new Uri("https://tokenmei.com/v1") }
);
foreach (var item in client.GetOpenAIModelClient().GetModels()) {
    Console.WriteLine(item.Id);
}
```

无 Key 或 Key 无效：

```json
{
  "error": {
    "message": "无效的 API Key",
    "type": "authentication_error",
    "param": null,
    "code": "invalid_api_key"
  }
}
```

## 2. 查余额

官方 SDK 没有对应方法，直接 HTTP 调。不计费。`balance` 固定两位小数并向下取整。字段见 [计费与产物](/docs/usage)。

```bash
curl $BASE/v1/balance \
  -H "Authorization: Bearer $MOMO_API_KEY"
```

```json
{
  "object": "balance",
  "balance": "12.50",
  "currency": "CNY",
  "scope": "tenant"
}
```

子账户 Key 的 `scope` 是 `sub_account`，金额是该子账户额度。

## 3. 跑一轮对话

从目录里挑一个对话模型。先非流式，再 `stream: true`。

```bash
curl https://tokenmei.com/v1/chat/completions \
  -H "Authorization: Bearer $MOMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_CHAT_MODEL",
    "messages": [{"role": "user", "content": "你好"}]
  }'
```

```javascript
const chat = await client.chat.completions.create({
  model: "YOUR_CHAT_MODEL",
  messages: [{ role: "user", content: "你好" }],
});
console.log(chat.choices[0].message.content);
```

```python
chat = client.chat.completions.create(
    model="YOUR_CHAT_MODEL",
    messages=[{"role": "user", "content": "你好"}],
)
print(chat.choices[0].message.content)
```

```go
chat, _ := client.Chat.Completions.New(context.TODO(), openai.ChatCompletionNewParams{
	Model: "YOUR_CHAT_MODEL",
	Messages: []openai.ChatCompletionMessageParamUnion{
		openai.UserMessage("你好"),
	},
})
fmt.Println(chat.Choices[0].Message.Content)
```

```php
$chat = $client->chat()->create([
    "model" => "YOUR_CHAT_MODEL",
    "messages" => [["role" => "user", "content" => "你好"]],
]);
echo $chat->choices[0]->message->content;
```

```java
ChatCompletion chat = client.chat().completions().create(
    ChatCompletionCreateParams.builder()
        .model("YOUR_CHAT_MODEL")
        .addUserMessage("你好")
        .build()
);
System.out.println(chat.choices().get(0).message().content());
```

```csharp
var chat = client.GetChatClient("YOUR_CHAT_MODEL").CompleteChat("你好");
Console.WriteLine(chat.Content[0].Text);
```

## 4. 生图 / 视频

生图用 `response_format: "url"`，保存返回的稳定地址。视频：`POST /v1/videos` 拿到 `id` 后轮询 `GET /v1/tasks/{id}`，直到 `completed` 再取 `url`（默认是平台稳定地址；个别关闭转存的模型可能直出上游地址）。异步生图同样用这条查询。完整字段见[生图](/docs/images)、[生视频](/docs/videos)、[任务查询](/docs/tasks)。

> **模型 id 以平台为准**
>
> 同一底层能力对外可能叫完全不同的 id。以 `GET /v1/models` 返回的 id 为准；未出现在该目录中的名称不可调用。

下一步看 [SDK 对照](/docs/sdk)，确认各路径与字段是否支持。

---

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

# 鉴权与限流

所有 `/v1` 请求都要带：

```http
Authorization: Bearer sk_live_...
Content-Type: application/json
```

SSE 对话请求同样带 JSON body 和 Bearer；响应才是 `text/event-stream`。

Key 无效、已吊销、或所属租户停用，一律 `401` + `invalid_api_key`。不要依赖 `OpenAI-Organization`，该请求头会被忽略。

> **不要把 Key 放进浏览器**
>
> 客户集成走服务端 SDK 或后端转发。CORS 面向管理台；请勿从任意前端域名直连 `/v1`。

## 额度

租户余额 ≤ 0 时，**非 GET** 请求返回 `429` + `insufficient_quota`。列模型、查询任务（`GET /v1/tasks/{id}`）、查询余额（`GET /v1/balance`）仍可访问。

`GET /v1/balance` 返回当前这把 Key 还能花的余额。主账户 Key 是租户余额；子账户 Key 是该子账户额度，看不到主账户余额。进行中的占用已经从返回值里扣掉。`balance` 固定两位小数并向下取整，账上仍按最多 6 位小数判断能否发起生成。字段、示例和 `0.009` 显示成 `"0.00"` 的情况见 [计费与产物](/docs/usage)。

充值记在租户上，不按 Key 分账。子账户额度由主账户划拨。

## 限流

按 **Key × 能力 × 自然分钟** 计数。默认（可被运营改成 Key 自己的 RPM，空则继承租户）：

| 能力 | 默认 RPM | 作用接口 |
|------|----------|----------|
| chat | 120 | `POST /v1/chat/completions`、`POST /v1/responses` |
| image | 60 | `POST /v1/images/generations` |
| video | 20 | `POST /v1/videos` |

`GET /v1/models`、`GET /v1/balance` 与任务查询（`GET /v1/tasks/{id}` 及其别名）不走这套 RPM。子账户管理（`/v1/sub-accounts`）使用单独的 management RPM（默认 60），且必须用**主账户** API Key；详见 [子账户](/docs/sub-accounts)。触发 chat/image/video 限流后 HTTP `429`：

```json
{
  "error": {
    "message": "触发限流",
    "type": "rate_limit_error",
    "param": null,
    "code": "rate_limit_exceeded"
  }
}
```

`insufficient_quota` 同样是 `429`、`type` 为 `rate_limit_error`，用 `code` 区分。响应**不包含** `Retry-After`；限流等到下一自然分钟，余额不足等充值。

## 探针

**GET** `/healthz`

无需鉴权，不在 `/v1` 下。正常返回 `{ "status": "ok" }`。负载均衡探活用这个，不要拿带 Key 的生成接口探活。

---

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

# SDK 对照

推荐用官方 OpenAI SDK，只改两处：`apiKey` 和 `baseURL`（基址 + `/v1`）。基址当前为 `https://tokenmei.com`。

> **视频与子账户以 REST 为准**
>
> 对话和生图可以走官方 OpenAI SDK。视频请 HTTP 调 `POST /v1/videos`，字段对齐 Seedance（`duration` / `ratio` / `resolution` / `first_frame` / `reference_images` 等）；snake_case 与 camelCase、常见媒体别名均可，详见[生视频](/docs/videos)。
>
> [子账户管理](/docs/sub-accounts)（`/v1/sub-accounts`）也无 SDK 封装，请直接 HTTP；须用**主账户** API Key。
>
> Vercel AI SDK 的 `experimental_generateVideo` 连接的是 ByteDance ModelArk / AI Gateway，**不能**把 `baseURL` 指到本平台就当 Seedance 用。

## 客户端

```bash
export MOMO_API_KEY=sk_live_xxx
export TU_BASE=https://tokenmei.com/v1
```

```javascript
import OpenAI from "openai";

export const client = new OpenAI({
  apiKey: process.env.MOMO_API_KEY,
  baseURL: "https://tokenmei.com/v1",
});
```

```python
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["MOMO_API_KEY"],
    base_url="https://tokenmei.com/v1",
)
```

```go
client := openai.NewClient(
	option.WithAPIKey(os.Getenv("MOMO_API_KEY")),
	option.WithBaseURL("https://tokenmei.com/v1"),
)
```

```php
$client = OpenAI::factory()
    ->withApiKey(getenv("MOMO_API_KEY"))
    ->withBaseUri("https://tokenmei.com/v1")
    ->make();
```

```java
OpenAIClient client = OpenAIOkHttpClient.builder()
    .apiKey(System.getenv("MOMO_API_KEY"))
    .baseUrl("https://tokenmei.com/v1")
    .build();
```

```csharp
var client = new OpenAIClient(
    new ApiKeyCredential(Environment.GetEnvironmentVariable("MOMO_API_KEY")),
    new OpenAIClientOptions { Endpoint = new Uri("https://tokenmei.com/v1") }
);
```

## 能直接用

| SDK 方法 | 对应路径 | 说明 |
|----------|----------|------|
| `models.list` / `models.retrieve` | `GET /v1/models` | `id` 是平台对外 id。扩展字段见下表；SDK 强类型通常读不到 |
| `chat.completions.create` | `POST /v1/chat/completions` | 文本 + Vision（`image_url`）+ 文件（`file` / `file_data`）+ function calling；`stream` 可用 |
| `responses.create` | `POST /v1/responses` | 文本 + `input_image` / `input_file` + function calling；`stream` 可用；与 chat 共用模型 |
| `images.generate` | `POST /v1/images/generations` | `prompt` / `n` / `size` / `response_format` |
| `images.edit` | `POST /v1/images/edits` | 需带 `image`；支持公网 URL / base64 / multipart 文件；`mask` 可传但不参与生成 |

图生图可用 `images.edit`，或在 `images.generate` 里加 `image`。输入形态详见[生图](/docs/images)。

## 会静默丢掉的字段

请求体开启了 whitelist：未声明的字段**直接丢掉，不报错**。下列字段会被忽略：

| 字段 | 说明 |
|------|------|
| `response_format` | chat 的 json schema |
| `OpenAI-Organization` | 请求头，忽略 |
| `stream_options` | 服务端会自行附带 usage |

Vision 的 `image_url` 与文件的 `file` / `input_file`（详见[对话](/docs/chat)、[Responses](/docs/responses)）**不会**被静默丢掉。`file_id` / `/v1/files` 不可用：content 里单独传 `file_id` 会 **400**，请改用 `file_data` 或公网 URL。

## 平台多出来的字段

| 位置 | 字段 | 含义 |
|------|------|------|
| `GET /v1/models` | `display_name` / `capability` | 展示名；`chat` / `image` / `video` |
| `GET /v1/models` | `features` / `limits` / `pricing` | 图生图、允许尺寸、对客售价；缺省则省略该对象 |
| `GET /v1/models` query | `capability` / `owned_by` | HTTP 可过滤；官方 `models.list()` 带不了 |
| 成功 `usage` | `cost.amount` / `cost.currency` | 对外售价；运营可关闭，关闭后字段不出现 |
| `GET /v1/balance` | `balance` / `currency` / `scope` | 当前 Key 可用余额。`balance` 固定两位小数并向下取整；官方 SDK 没有对应方法，直接 HTTP 调用。详见 [计费与产物](/docs/usage) |
| 生图请求 | `image` | 公网 URL / base64 / multipart 文件（先转存）；`images.edit` 必填；详见[生图](/docs/images) |
| 视频请求 | `duration` / `ratio` / `first_frame` / `reference_*` | 对齐 Seedance；camelCase 与完整媒体别名见[生视频](/docs/videos) |
| 视频响应 | `url` / `progress` / `status` | 见[生视频](/docs/videos)、[任务查询](/docs/tasks) |

## 不支持的路径

`/v1/embeddings`、`/v1/audio/*`、`/v1/files`。目录里即便有 embedding / 语音模型，调用也返回 `capability_not_enabled`。图和视频进度请查 `GET /v1/tasks/{id}`，没有单独的厂商侧 task 协议；统一用平台 task API。

---

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

# Agent / CLI

把平台模型能力接入 Cursor / Claude Desktop / Codex，或在终端、脚本里直接调用。工具与 `/v1` 使用同一把 API Key，按租户余额计费。

> `@momotoken/api-mcp` 发布到 npm 后可用 `npx`；本地开发阶段可运行 `node packages/api-mcp/src/cli.js`。

## 准备

- Node.js **>= 18.3**（推荐 20 LTS）
- 一把 `sk_live_...` API Key（在租户台创建）

```bash
export MOMO_API_BASE_URL=https://tokenmei.com
export MOMO_API_KEY=sk_live_...
```

验证配置与连通性：

```bash
npx -y @momotoken/api-mcp doctor
```

## 命令行

| 命令 | 作用 |
|------|------|
| `momo-api models [--capability chat\|image\|video]` | 列出可用模型 |
| `momo-api models get <id>` | 模型详情 |
| `momo-api chat [prompt] -m <model>` | 对话，默认流式 |
| `momo-api image generate\|edit <prompt>` | 生图 / 图生图 |
| `momo-api video create <prompt>` | 创建视频任务 |
| `momo-api video get\|wait\|download <id>` | 查询、等待、下载视频 |
| `momo-api task get\|wait <id>` | 通用任务查询 |
| `momo-api task ls` | 本机任务记录 |
| `momo-api login` / `logout` | 保存 / 移除配置里的 Key |
| `momo-api mcp --print-config` | 输出 MCP 配置片段 |

常用示例：

```bash
# 对话（可管道）
momo-api chat "用三句话解释 MCP" -m doubao-seed-1.6

# 生图并落盘
momo-api image generate "雨夜霓虹街头的橙猫" -m <image-model> \
  --size 1024x1024 -o ./out/

# 视频：创建 → 等待 → 下载
momo-api video create "镜头跟随橙猫穿过雨夜街道" -m <video-model> \
  --duration 5 --ratio 16:9 --resolution 720p --json
momo-api video wait video_xxx --timeout 16m
momo-api video download video_xxx -o ./out/cat.mp4
```

生图默认同步；加 `--async` 返回任务 id，用 `momo-api task wait <id> --out ./out/` 取结果。视频始终异步。

常用参数：`--n`、`--size`、`--aspect-ratio`、`--quality`、`--ref`（参考图，可重复）、`--duration`、`--ratio`、`--resolution`、`--audio`、`--watermark`、`--out`、`--force`、`--json`、`--jsonl`、`--dry-run`、`--timeout`。

## 配置

优先级：命令行参数 > 环境变量 > profile 文件。

| 变量 | 说明 |
|------|------|
| `MOMO_API_BASE_URL` | API 源站，如 `https://tokenmei.com` |
| `MOMO_API_KEY` | `sk_live_...` |
| `MOMO_API_PROFILE` | 选择 profile |
| `MOMO_API_HOME` | 覆盖配置目录 |

配置文件在 `~/.config/momo-api/config.json`（Windows 为 `%APPDATA%\momo-api\config.json`），目录 `0700`、文件 `0600`。`momo-api login` 会验证 Key 后写入：

```bash
echo "$MOMO_API_KEY" | momo-api login --base-url https://tokenmei.com
momo-api profile list
momo-api profile use default
```

## MCP

```json
{
  "mcpServers": {
    "momo-api": {
      "command": "npx",
      "args": ["-y", "@momotoken/api-mcp", "mcp"],
      "env": {
        "MOMO_API_BASE_URL": "https://tokenmei.com",
        "MOMO_API_KEY": "sk_live_..."
      }
    }
  }
}
```

把 `momo-api mcp --print-config` 的输出粘贴到客户端即可。

### 工具

| 工具 | 说明 |
|------|------|
| `momo_models_list` | 列模型；生成前先调用 |
| `momo_models_get` | 单个模型与价格 |
| `momo_chat` | 对话（缓冲返回） |
| `momo_image_generate` | 生图，默认异步 |
| `momo_image_edit` | 带参考图的图生图 |
| `momo_video_create` | 创建视频任务 |
| `momo_task_get` | 查询一次任务 |
| `momo_task_wait` | 等待最多 45 秒，返回 `done` |
| `momo_asset_inline` | 把 ≤4MB 图片内联进上下文 |

### 长任务

生图/生视频返回 `taskId` 时，继续调用 `momo_task_wait`，不要把 `momo_video_create` / `momo_image_generate` 再调一次——重复创建会重复扣费。单次 `momo_task_wait` 最多 45 秒，未完成时按返回的 `retryAfterSeconds` 继续。

## 退出码

| 退出码 | 含义 |
|--------|------|
| 0 | 成功 |
| 2 | 参数 / 配置错误 |
| 3 | API Key 无效 |
| 4 | 余额不足 |
| 5 | 触发限流 |
| 6 | 模型或任务不存在 |
| 7 | 能力未开通 |
| 8 | 上游错误 |
| 9 | 超时 / 网络错误 |
| 10 | 本地文件错误 |

## 安全与限制

- 所有输出中的 Key 都会脱敏；非 localhost 强制 HTTPS。
- 本地参考图上限 10MB；下载上限 512MB，先写 `.part` 再改名。
- 生成类 POST 不会自动重试（避免重复扣费）；`GET` 失败会有限重试。
- 任务完成后 URL 有保留期，需要长期保存请下载到本地。

CLI / MCP 不封装余额查询。需要时直接调 `GET /v1/balance`，见 [计费与产物](/docs/usage)。

更多契约见 [模型](/docs/models)、[对话](/docs/chat)、[生图](/docs/images)、[生视频](/docs/videos)、[任务查询](/docs/tasks)、[计费与产物](/docs/usage)、[错误码](/docs/errors)。

---

*更新日期: 2026-08-22*

# 模型

**GET** `/v1/models`

列出当前 Key 可见、且已对客开通的模型。不计 RPM、不计费。

可选过滤：`capability`（`chat` / `image` / `video`）、`owned_by`（大模型厂商 id）。官方 OpenAI SDK 的 `models.list()` 带不了这些参数，HTTP 可直接加 query。

```bash
curl "https://tokenmei.com/v1/models?capability=image" \
  -H "Authorization: Bearer $MOMO_API_KEY"
```

```javascript
const models = await client.models.list();
for (const item of models.data) {
  console.log(item.id, item.owned_by);
}
```

```python
for item in client.models.list().data:
    print(item.id, item.owned_by)
```

```go
models, _ := client.Models.List(context.TODO(), openai.ModelListParams{})
for _, item := range models.Data {
	fmt.Println(item.ID, item.OwnedBy)
}
```

```php
foreach ($client->models()->list()->data as $item) {
    echo $item->id, " ", $item->ownedBy, PHP_EOL;
}
```

```java
for (Model item : client.models().list().data()) {
    System.out.println(item.id() + " " + item.ownedBy());
}
```

```csharp
foreach (var item in client.GetOpenAIModelClient().GetModels()) {
    Console.WriteLine($"{item.Id} {item.OwnedBy}");
}
```

```json
{
  "object": "list",
  "data": [
    {
      "id": "doubao-seed-1.6",
      "object": "model",
      "created": 1710000000,
      "owned_by": "bytedance",
      "display_name": "doubao-seed-1.6",
      "vendor": "bytedance",
      "recommended": false,
      "capability": "chat",
      "pricing": {
        "currency": "CNY",
        "unit": "token_1m",
        "amount": "0.8",
        "input_amount": "0.8",
        "output_amount": "2"
      }
    },
    {
      "id": "doubao-seedream-4-0-250828",
      "object": "model",
      "created": 1710000000,
      "owned_by": "bytedance",
      "display_name": "doubao-seedream-4-0-250828",
      "vendor": "bytedance",
      "capability": "image",
      "pricing": {
        "currency": "CNY",
        "unit": "image",
        "amount": "0.20",
        "size_multipliers": { "2048x2048": "1.5" }
      }
    }
  ]
}
```

OpenAI 核心字段保持不变，扩展字段按需出现：没有售价时，`pricing` 不会出现，不会填 `null`。

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | string | 对外模型 id，请求里填这个 |
| `object` | string | 固定 `model` |
| `created` | int | Unix 秒 |
| `owned_by` | string | 大模型厂商 id（与 `vendor` 一致）；未配置时为空字符串，不暴露上游渠道 |
| `display_name` | string | 与 `id` 相同 |
| `vendor` | string | 大模型厂商 id（Logo stem），有配置时出现 |
| `description` | string | 可选说明介绍 |
| `capability` | string | `chat` / `image` / `video`，决定走哪条生成路径 |
| `recommended` | boolean | 是否为推荐模型；C 端模型列表展示「推荐」标签 |
| `pricing` | object | 对客售价；未配价格则省略。不含成本明细 |

`pricing` 金额都是十进制字符串：

| 字段 | 说明 |
|------|------|
| `currency` | 如 `CNY` |
| `unit` | `token` / `token_1k` / `token_1m` / `image` / `request` / `second` |
| `amount` | 默认单价（chat 为输入价） |
| `input_amount` / `output_amount` | chat 的输入 / 输出单价，单位为每百万 token |
| `size_multipliers` | 尺寸倍率，如 `{ "2048x2048": "1.5" }` |
| `price_table` | 视频价目表（`mode` + `rates`）；仅客户价 |

同一 `id` 只对应一种能力。官方 SDK 的强类型对象通常读不到扩展字段，需要 HTTP 或解析原始 JSON。

**GET** `/v1/models/{model}`

`{model}` 是对外 `id`。形状与列表里的单条相同。不存在或对你不可见：`404` + `model_not_found`，`param` 为 `model`。

```bash
curl https://tokenmei.com/v1/models/doubao-seed-1.6 \
  -H "Authorization: Bearer $MOMO_API_KEY"
```

```javascript
const model = await client.models.retrieve("doubao-seed-1.6");
console.log(model.id);
```

```python
model = client.models.retrieve("doubao-seed-1.6")
print(model.id)
```

```go
model, _ := client.Models.Get(context.TODO(), "doubao-seed-1.6")
fmt.Println(model.ID)
```

```php
$model = $client->models()->retrieve("doubao-seed-1.6");
echo $model->id;
```

```java
Model model = client.models().retrieve("doubao-seed-1.6");
System.out.println(model.id());
```

```csharp
var model = client.GetOpenAIModelClient().GetModel("doubao-seed-1.6");
Console.WriteLine(model.Id);
```

过滤条件（同时满足才出现）：平台已开放、模型已启用、能力为 chat / image / video。未配价格的模型即使被误列，调用时仍是 `model_not_found`。

---

*更新日期: 2026-10-10*

# 对话

**POST** `/v1/chat/completions`

支持**文本**、**Vision 图文**（OpenAI 兼容 `image_url` content part）、**文件附件**（OpenAI 兼容 `file` content part，`file_data` / 公网 URL）和 **function calling**。网关不执行函数，只把 `tools` 交给模型服务，并把 `tool_calls` 回给调用方。`response_format` 与 `web_search` 等内置工具会被拒绝或忽略：未列出的字段静默忽略；非 `function` 的 `tools` 返回 400。`file_id` / `/v1/files` 不可用，传入会返回 400。是否真正看图/读文件、是否会发起函数调用，取决于所选模型。

OpenAI Responses 形态见 [`POST /v1/responses`](/docs/responses)（同样支持 `input_image` / `input_file`）。

## 请求

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `model` | string | 是 | 对外 id |
| `messages` | array | 是 | 至少一条。`role` 为 `system` / `user` / `assistant` / `tool`。助手调用函数时带 `tool_calls`，`content` 可为 `null`。`role: tool` 必须带 `tool_call_id` |
| `stream` | boolean | 否 | `true` 时 SSE；函数调用以 `delta.tool_calls` 分片返回 |
| `temperature` | number | 否 | 作用于所选模型 |
| `max_tokens` | number | 否 | 作用于所选模型 |
| `tools` | array | 否 | 仅 `type: "function"`。每项含 `function.name`，可选 `description` / `parameters` / `strict` |
| `tool_choice` | string \| object | 否 | `none` / `auto` / `required`，或 `{ "type": "function", "function": { "name": "..." } }`。设置时必须同时传 `tools` |
| `parallel_tool_calls` | boolean | 否 | 是否允许同一次回复里并行多个函数调用。设置时必须同时传 `tools` |

### `messages[].content`

| 形态 | 说明 |
|------|------|
| `string` | 纯文本 |
| `array` | content parts：`text`、`image_url`、`file`（见下） |

`image_url.url` 支持：

| 形态 | 说明 |
|------|------|
| 公网 URL | `https://...`（该地址需可公网访问） |
| Data URL / base64 | `data:image/png;base64,...`；网关先转存为平台公网 URL 再交给模型服务 |
| 对象简写 | `image_url` 也可直接为字符串 URL |

可选 `image_url.detail`（如 `low` / `high` / `auto`）作用于所选模型。

#### 文件 part（`type: "file"`）

| 字段 | 说明 |
|------|------|
| `file.file_data` | Data URL / base64，或公网 HTTPS URL；内嵌数据会先转存为平台公网 URL，再以 `file_data` 交给上游 |
| `file.filename` | 可选文件名（如 `doc.pdf`） |
| `file.file_id` | **不支持**（无 `/v1/files`），单独传入返回 400 |

本地文件路径不支持。请用 `file_data`（含 data URL）或公网 URL，不要传 `file_id`。

Vision 示例：

```json
{
  "model": "YOUR_CHAT_MODEL",
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "图里有什么？" },
        {
          "type": "image_url",
          "image_url": { "url": "https://cdn.example.com/cat.png" }
        }
      ]
    }
  ]
}
```

Function calling 示例（调用方拿到 `tool_calls` 后自行执行，再把 `role: "tool"` 的结果发回）：

```json
{
  "model": "YOUR_CHAT_MODEL",
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "parameters": {
          "type": "object",
          "properties": { "city": { "type": "string" } },
          "required": ["city"]
        }
      }
    }
  ],
  "messages": [
    { "role": "user", "content": "巴黎天气如何？" }
  ]
}
```

同步响应里 `choices[0].message.tool_calls` 为函数调用，`finish_reason` 为 `tool_calls`。流式响应里参数在 `delta.tool_calls[].function.arguments` 中分段到达。

```bash
curl https://tokenmei.com/v1/chat/completions \
  -H "Authorization: Bearer $MOMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_CHAT_MODEL",
    "messages": [
      {"role": "system", "content": "你是助手"},
      {"role": "user", "content": "你好"}
    ],
    "temperature": 0.7,
    "max_tokens": 2048
  }'
```

```javascript
const chat = await client.chat.completions.create({
  model: "YOUR_CHAT_MODEL",
  messages: [
    { role: "system", content: "你是助手" },
    { role: "user", content: "你好" },
  ],
  temperature: 0.7,
  max_tokens: 2048,
});
console.log(chat.id);
console.log(chat.choices[0].message.content);
console.log(chat.usage);
```

```python
chat = client.chat.completions.create(
    model="YOUR_CHAT_MODEL",
    messages=[
        {"role": "system", "content": "你是助手"},
        {"role": "user", "content": "你好"},
    ],
    temperature=0.7,
    max_tokens=2048,
)
print(chat.id)
print(chat.choices[0].message.content)
print(chat.usage)
```

```go
chat, _ := client.Chat.Completions.New(context.TODO(), openai.ChatCompletionNewParams{
	Model: "YOUR_CHAT_MODEL",
	Messages: []openai.ChatCompletionMessageParamUnion{
		openai.SystemMessage("你是助手"),
		openai.UserMessage("你好"),
	},
	Temperature: openai.Float(0.7),
	MaxTokens:   openai.Int(2048),
})
fmt.Println(chat.ID)
fmt.Println(chat.Choices[0].Message.Content)
fmt.Println(chat.Usage)
```

```php
$chat = $client->chat()->create([
    "model" => "YOUR_CHAT_MODEL",
    "messages" => [
        ["role" => "system", "content" => "你是助手"],
        ["role" => "user", "content" => "你好"],
    ],
    "temperature" => 0.7,
    "max_tokens" => 2048,
]);
echo $chat->id, PHP_EOL;
echo $chat->choices[0]->message->content, PHP_EOL;
print_r($chat->usage);
```

```java
ChatCompletion chat = client.chat().completions().create(
    ChatCompletionCreateParams.builder()
        .model("YOUR_CHAT_MODEL")
        .addSystemMessage("你是助手")
        .addUserMessage("你好")
        .temperature(0.7)
        .maxTokens(2048)
        .build()
);
System.out.println(chat.id());
System.out.println(chat.choices().get(0).message().content());
System.out.println(chat.usage());
```

```csharp
var chat = client.GetChatClient("YOUR_CHAT_MODEL").CompleteChat(
    new SystemChatMessage("你是助手"),
    new UserChatMessage("你好"),
    new ChatCompletionOptions { Temperature = 0.7f, MaxOutputTokenCount = 2048 }
);
Console.WriteLine(chat.Id);
Console.WriteLine(chat.Content[0].Text);
Console.WriteLine(chat.Usage);
```

## 非流式响应

```json
{
  "id": "chatcmpl_a1b2c3d4e5f6",
  "object": "chat.completion",
  "created": 1710000000,
  "model": "YOUR_CHAT_MODEL",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "你好！" },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 8,
    "total_tokens": 28,
    "cost": { "amount": "0.0021", "currency": "CNY" }
  }
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | string | 前缀固定 `chatcmpl_` |
| `object` | string | 固定 `chat.completion` |
| `created` | int | Unix 秒 |
| `model` | string | 对外模型 id |
| `choices` | array | 每项含 `index`、`message`、`finish_reason` |
| `choices[].message.role` | string | `assistant` |
| `choices[].message.content` | string | 回复文本 |
| `choices[].finish_reason` | string | 如 `stop` |
| `usage.prompt_tokens` | int | 输入 token |
| `usage.completion_tokens` | int | 输出 token |
| `usage.total_tokens` | int | 合计 |
| `usage.cost` | object | 可选。`amount` 为对外售价字符串，`currency` 为 `CNY`。运营可在系统设置里关闭，关闭后字段不出现 |

## 流式

`stream: true` 时 HTTP 仍是 **200**，`Content-Type: text/event-stream`。每帧 `data: {json}`，结束 `data: [DONE]`。最后一帧（`[DONE]` 之前）带 `usage` 与 `finish_reason`。扣费发生在流正常结束后，按实际消耗的 token（usage），不是按 `max_tokens`。

```bash
curl -N https://tokenmei.com/v1/chat/completions \
  -H "Authorization: Bearer $MOMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_CHAT_MODEL",
    "messages": [{"role": "user", "content": "你好"}],
    "stream": true
  }'
```

```javascript
const stream = await client.chat.completions.create({
  model: "YOUR_CHAT_MODEL",
  messages: [{ role: "user", content: "你好" }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}
```

```python
stream = client.chat.completions.create(
    model="YOUR_CHAT_MODEL",
    messages=[{"role": "user", "content": "你好"}],
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)
```

```go
stream := client.Chat.Completions.NewStreaming(context.TODO(), openai.ChatCompletionNewParams{
	Model: "YOUR_CHAT_MODEL",
	Messages: []openai.ChatCompletionMessageParamUnion{
		openai.UserMessage("你好"),
	},
})
for stream.Next() {
	chunk := stream.Current()
	if len(chunk.Choices) > 0 {
		fmt.Print(chunk.Choices[0].Delta.Content)
	}
}
```

```php
$stream = $client->chat()->createStreamed([
    "model" => "YOUR_CHAT_MODEL",
    "messages" => [["role" => "user", "content" => "你好"]],
]);
foreach ($stream as $chunk) {
    echo $chunk->choices[0]->delta->content ?? "";
}
```

```java
client.chat().completions().createStreaming(
    ChatCompletionCreateParams.builder()
        .model("YOUR_CHAT_MODEL")
        .addUserMessage("你好")
        .build()
).subscribe(chunk -> {
    if (!chunk.choices().isEmpty()) {
        chunk.choices().get(0).delta().content().ifPresent(System.out::print);
    }
});
```

```csharp
await foreach (var chunk in client.GetChatClient("YOUR_CHAT_MODEL")
    .CompleteChatStreamingAsync("你好")) {
    Console.Write(chunk.ContentUpdate[0].Text);
}
```

增量帧示例：

```
data: {"id":"chatcmpl_…","object":"chat.completion.chunk","created":1710000000,"model":"YOUR_CHAT_MODEL","choices":[{"index":0,"delta":{"content":"你"},"finish_reason":null}]}

data: {"id":"chatcmpl_…","object":"chat.completion.chunk","created":1710000000,"model":"YOUR_CHAT_MODEL","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":8,"completion_tokens":2,"total_tokens":10}}

data: [DONE]
```

| 字段 | 说明 |
|------|------|
| `data: {json}` | 增量帧 |
| `choices[].delta.content` | 文本增量，可能为空 |
| 最后一帧 | `[DONE]` 之前，带 `usage` 与 `finish_reason` |
| `data: [DONE]` | 结束标记 |
| `data: {"error":…}` | 模型调用失败；HTTP 仍可能是 200，不扣费 |

模型调用失败时不要只看 HTTP 状态。失败的流不会扣费。中途断连以服务端是否跑完结算为准；不要假设客户端 abort 一定退款。

---

*更新日期: 2026-10-10*

# Responses

**POST** `/v1/responses`

OpenAI **Responses API** 兼容入口，与 [`/v1/chat/completions`](/docs/chat) 共用 chat 模型与计费。服务端会把 `input` / `instructions` 转成 chat messages 交给模型服务；返回 `object: "response"` 与 `output` 数组。

支持文本、Vision、文件附件与 function calling。`input` message 的 content 可为字符串，或含 `input_text` / `input_image` / `input_file`（也会接受 chat 风格的 `text` / `image_url` / `file`）的数组。`input_file` 可用 `file_data`（data URL / base64）或公网 `file_url`；内嵌数据会先转存。网关把 Responses 的 function tools 转成 chat `tools` 交给模型服务，再把结果放进 `output` 里的 `function_call`。网关不执行函数。`previous_response_id`、有状态 `store` 以及 `web_search` 等内置工具会被忽略或返回 400。`file_id` / `/v1/files` 不可用，传入返回 400。

## 请求

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `model` | string | 是 | 对外 id（capability = chat） |
| `input` | string \| array | 是 | 字符串等价于一条 user 文本；数组为 message / item 列表 |
| `instructions` | string | 否 | 作为 system 消息前置 |
| `stream` | boolean | 否 | `true` 时 SSE（Responses 事件流） |
| `temperature` | number | 否 | 作用于所选模型 |
| `max_output_tokens` | number | 否 | 映射为所选模型的 `max_tokens` |
| `tools` | array | 否 | 仅 `type: "function"`，字段为顶层 `name` / `description` / `parameters` / `strict`。也接受 chat 嵌套的 `function.name` |
| `tool_choice` | string \| object | 否 | `none` / `auto` / `required`，或 `{ "type": "function", "name": "..." }`。设置时必须同时传 `tools` |
| `parallel_tool_calls` | boolean | 否 | 是否允许并行函数调用。设置时必须同时传 `tools` |

多轮时在 `input` 里带回上一次的 `function_call`（`call_id`、`name`、`arguments`）和 `function_call_output`（`call_id`、`output`）。连续的 `function_call` 会合成一条带多个 `tool_calls` 的 assistant 消息。

```bash
curl https://tokenmei.com/v1/responses \
  -H "Authorization: Bearer $MOMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_CHAT_MODEL",
    "instructions": "你是助手",
    "input": "你好",
    "temperature": 0.7,
    "max_output_tokens": 2048
  }'
```

```javascript
const response = await client.responses.create({
  model: "YOUR_CHAT_MODEL",
  instructions: "你是助手",
  input: "你好",
  temperature: 0.7,
  max_output_tokens: 2048,
});
console.log(response.id);
console.log(response.output_text);
console.log(response.usage);
```

```python
response = client.responses.create(
    model="YOUR_CHAT_MODEL",
    instructions="你是助手",
    input="你好",
    temperature=0.7,
    max_output_tokens=2048,
)
print(response.id)
print(response.output_text)
print(response.usage)
```

## 响应

同步成功时 `status` 为 `completed`（触达 `max_output_tokens` 时可能为 `incomplete`）。文本在 `output[].content[].text`；官方 SDK 可用 `output_text` 快捷读取。

`usage` 使用 Responses 字段名：`input_tokens` / `output_tokens` / `total_tokens`。若平台开启对客展示费用，可能附带 `usage.cost`。

## 流式

`stream: true` 时返回 SSE，事件类型包括 `response.created`、`response.output_text.delta`、`response.completed` 等，与 OpenAI Responses 流式约定一致。

```bash
curl -N https://tokenmei.com/v1/responses \
  -H "Authorization: Bearer $MOMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_CHAT_MODEL",
    "input": "写一句问候",
    "stream": true
  }'
```

```javascript
const stream = await client.responses.create({
  model: "YOUR_CHAT_MODEL",
  input: "写一句问候",
  stream: true,
});
for await (const event of stream) {
  if (event.type === "response.output_text.delta") {
    process.stdout.write(event.delta);
  }
}
```

```python
with client.responses.stream(
    model="YOUR_CHAT_MODEL",
    input="写一句问候",
) as stream:
    for event in stream:
        if event.type == "response.output_text.delta":
            print(event.delta, end="")
```

---

*更新日期: 2026-08-29*

# 生图

**POST** `/v1/images/generations`

默认同步接口：网关会等到生成完成或超时（最多 **5 分钟**）。超时 `504` + `gateway_timeout`，不扣费。图生图也可走兼容路径 `POST /v1/images/edits`（见下方）。

同步成功/失败都会写入平台任务记录，**门户与管理端任务列表可见**（`img_…`）。同步成功响应体仍是 OpenAI 风格的 `{ created, data, usage }`，**不含**对外 `id`。

传 `async: true` 时，接口立即返回**对外 task id**（HTTP 200），用 `GET /v1/tasks/{id}` 轮询完成结果；不传或传 `false` 时走同步路径，直接返回最终图片。`GET /v1/images/{id}` 是同一查询的别名。

## 请求

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `model` | string | 是 | 对外 id（`GET /v1/models?capability=image`） |
| `prompt` | string | 是 | 文本提示 |
| `n` | int ≥ 1 | 否 | 请求张数；**计费按实际返回张数**；部分模型仅支持 1 |
| `size` | string | 否 | 像素如 `1024x1024`，或档位如 `2K`（Seedream）；以该模型实际支持为准 |
| `aspect_ratio` | string | 否 | 如 `16:9` / `1:1`；Gemini / 部分模型优先用；也可用 `aspectRatio` |
| `quality` | string | 否 | 如 `low` / `high` / `hd`；GPT-Image 等模型生效 |
| `background` | `auto` \| `opaque` \| `transparent` | 否 | GPT-Image 背景透明度 |
| `moderation` | `auto` \| `low` | 否 | GPT-Image 内容审核强度 |
| `output_format` | `png` \| `jpeg` | 否 | Seedream 输出编码 |
| `watermark` | boolean | 否 | Seedream「AI 生成」水印 |
| `optimize_prompt_options` | object | 否 | Seedream 提示词优化，`{ "mode": "standard" \| "fast" }` |
| `sequential_image_generation` | `auto` \| `disabled` | 否 | Seedream 组图 |
| `sequential_image_generation_options` | object | 否 | `{ "max_images": number }`，组图上限 |
| `async` | boolean | 否 | `true` 时立即返回 task id，走轮询；缺省或 `false` 走同步 |
| `response_format` | `url` \| `b64_json` | 否 | 默认 `url`。也可用 `responseFormat` |
| `image` / `images` | string \| file \| string[] | 否 | 图生图参考。输入形态与别名见下方 |

> **一套契约，多厂商差异由平台处理**
>
> 对外始终是 OpenAI 风格的 `/v1/images/generations`。不同模型族（Seedream、GPT-Image、Gemini / Banana、Grok 等）的差异由平台统一处理；客户端只需按本文档字段调用，不要照搬各模型自有文档。未声明支持的字段会被忽略或拒绝。

### 常见模型族参数习惯

| 系列 | `size` 习惯 | 参考图 |
|------|-------------|--------|
| Seedream | `2K` / `2048x2048` 等档位或像素 | `image` / `images` |
| ChatGPT / GPT-Image / DALL·E | `1024x1024`、`1536x1024`、`auto` | `image`（部分模型支持多图） |
| Gemini / Imagen / Banana | 可用 `aspect_ratio`，或用像素 `size` 推导比例 | `image` / `images` |
| Grok 生图 | 随模型而定；常见像素尺寸 | 视该模型是否支持 |

换模型时只改 `model`（及该模型文档/列表里给出的可选参数），路径与鉴权不变。

```bash
curl https://tokenmei.com/v1/images/generations \
  -H "Authorization: Bearer $MOMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_IMAGE_MODEL",
    "prompt": "一只橙猫走在雨夜霓虹街头",
    "n": 1,
    "size": "1024x1024",
    "response_format": "url"
  }'
```

```javascript
const image = await client.images.generate({
  model: "YOUR_IMAGE_MODEL",
  prompt: "一只橙猫走在雨夜霓虹街头",
  n: 1,
  size: "1024x1024",
  response_format: "url",
});
console.log(image.data[0].url);
console.log(image.usage);
```

```python
image = client.images.generate(
    model="YOUR_IMAGE_MODEL",
    prompt="一只橙猫走在雨夜霓虹街头",
    n=1,
    size="1024x1024",
    response_format="url",
)
print(image.data[0].url)
print(image.usage)
```

```go
image, _ := client.Images.Generate(context.TODO(), openai.ImageGenerateParams{
	Model:          "YOUR_IMAGE_MODEL",
	Prompt:         "一只橙猫走在雨夜霓虹街头",
	N:              openai.Int(1),
	Size:           openai.ImageGenerateParamsSize1024x1024,
	ResponseFormat: openai.ImageGenerateParamsResponseFormatURL,
})
fmt.Println(image.Data[0].URL)
fmt.Println(image.Usage)
```

```php
$image = $client->images()->create([
    "model" => "YOUR_IMAGE_MODEL",
    "prompt" => "一只橙猫走在雨夜霓虹街头",
    "n" => 1,
    "size" => "1024x1024",
    "response_format" => "url",
]);
echo $image->data[0]->url, PHP_EOL;
print_r($image->usage);
```

```java
ImagesResponse image = client.images().generate(
    ImageGenerateParams.builder()
        .model("YOUR_IMAGE_MODEL")
        .prompt("一只橙猫走在雨夜霓虹街头")
        .n(1L)
        .size(ImageGenerateParams.Size._1024X1024)
        .responseFormat(ImageGenerateParams.ResponseFormat.URL)
        .build()
);
System.out.println(image.data().get(0).url());
System.out.println(image.usage());
```

```csharp
var image = client.GetImageClient("YOUR_IMAGE_MODEL").GenerateImage(
    "一只橙猫走在雨夜霓虹街头",
    new ImageGenerationOptions { Size = GeneratedImageSize.W1024xH1024 }
);
Console.WriteLine(image.Value.ImageUri);
```

### 参考图输入形态

`image` / `images` 及下方别名，在 `generations` 与 `edits` 上支持三种入参（多值时取**第一张**）。文件与 base64 会先转存为平台公网 URL，再交给模型服务。

| 形态 | 怎么传 | 说明 |
|------|--------|------|
| **公网 URL** | JSON 字符串，如 `"https://cdn.example.com/ref.png"` | `http://` / `https://` 可直接用；该地址需可公网访问 |
| **Base64** | `data:image/png;base64,...`，或足够长且可识别为图片的裸 base64 | 网关解码后转存；不要传本机文件路径冒充字符串 |
| **文件流** | `multipart/form-data` 字段（如 `-F image=@ref.png`） | 与 OpenAI `images.edit` 常见写法一致；单文件上限约 10MB |

**不支持**客户端本机路径（如 `/Users/.../a.png`、`./ref.png`、`C:\...`）。服务端不会读你的磁盘；请改成上传文件、公网 URL 或 base64。

字段名别名（写全，含 camelCase / snake_case）：`image`、`image_url`、`imageUrl`、`images`、`image_urls`、`imageUrls`、`input_image`、`inputImage`、`input_reference`、`inputReference`、`reference_image`、`referenceImage`、`reference_images`、`referenceImages`、`first_frame`、`firstFrame`、`first_frame_image`、`firstFrameImage`、`init_image`、`initImage`、`file`。`response_format` 也可用 `responseFormat`。

公网 URL 示例：

```json
{
  "model": "YOUR_IMAGE_MODEL",
  "prompt": "改成水墨风",
  "image": "https://cdn.example.com/ref.png"
}
```

Base64（data URL）示例：

```json
{
  "model": "YOUR_IMAGE_MODEL",
  "prompt": "改成水墨风",
  "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
}
```

Multipart 文件示例（`generations` 与 `edits` 均可）：

```bash
curl $BASE/v1/images/generations \
  -H "Authorization: Bearer $MOMO_API_KEY" \
  -F model=YOUR_IMAGE_MODEL \
  -F prompt="改成水墨风" \
  -F image=@ref.png \
  -F response_format=url
```

SDK 若不允许额外字段，用 HTTP 调同一路径，或改用下方的 edits。

**POST** `/v1/images/edits`

OpenAI 兼容图编辑入口。与 `images/generations` + `image` **同一下游链路**；差别是 **`image` 必填**。接受 JSON 或 `multipart/form-data`（官方 SDK `images.edit` 常见写法）。输入形态同上表（URL / base64 / 文件流）。

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `model` | string | 是 | 对外 id（平台必填；OpenAI 官方有时可省略） |
| `prompt` | string | 是 | 编辑说明 |
| `image` | string \| file | 是 | 源图；形态与别名见「参考图输入形态」 |
| `mask` | string \| file | 否 | 兼容 OpenAI；同样支持 URL / base64 / 文件；**可传但不参与生成** |
| `n` | int ≥ 1 | 否 | 同 generations |
| `size` | string | 否 | 同 generations |
| `response_format` | `url` \| `b64_json` | 否 | 同 generations；也可用 `responseFormat` |
| `async` | boolean | 否 | 同 generations |

```bash
curl $BASE/v1/images/edits \
  -H "Authorization: Bearer $MOMO_API_KEY" \
  -F model=YOUR_IMAGE_MODEL \
  -F prompt="改成水墨风" \
  -F image=@ref.png
```

响应形状与 `POST /v1/images/generations` 相同。

## 响应

```json
{
  "created": 1710000000,
  "data": [
    { "url": "https://cdn.example.com/a/xxx.png", "revised_prompt": null }
  ],
  "usage": {
    "images_generated": 1,
    "cost": { "amount": "0.2200", "currency": "CNY" }
  }
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `created` | int | Unix 秒 |
| `data` | array | 每项一张图；计费按 `data.length`，不按请求里的 `n` |
| `data[].url` | string | `response_format=url` 时为平台转存后的稳定地址，不是临时链接 |
| `data[].b64_json` | string | `response_format=b64_json` 时直接给 base64，可跳过转存 |
| `data[].revised_prompt` | null | 固定为 `null` |
| `usage.images_generated` | int | 实际张数 |
| `usage.cost` | object | 可选，同对话的对外售价 |

`b64_json` 单项形如：

```json
{ "b64_json": "...", "revised_prompt": null }
```

> **计费张数**
>
> 按 `data.length` 扣，不按请求里的 `n`。若一张都没返回，按 1 张计价前会先当失败（`upstream_error`）。失败整单不扣。

## 任务轮询（`async: true`）

`async: true` 时，`POST /v1/images/generations` 立即返回 task：

```json
{
  "id": "img_a1b2c3d4e5f6",
  "object": "image",
  "model": "YOUR_IMAGE_MODEL",
  "status": "queued",
  "progress": 0,
  "created_at": 1710000000,
  "completed_at": null,
  "error": null
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | string | 前缀 `img_`，用于轮询 |
| `object` | string | 固定 `image` |
| `model` | string | 对外模型 id |
| `status` | string | `queued` / `in_progress` / `completed` / `failed` |
| `progress` | int | 0–100 |
| `created_at` | int | Unix 秒 |
| `completed_at` | int \| null | 未完成时为 `null` |
| `error` | string \| null | 成功为 `null`，失败为说明字符串 |
| `data` | array | 仅 `completed` 时出现，形状与同步生图一致 |

用这个 `id` 轮询（推荐统一路径）：

**GET** `/v1/tasks/{id}`

`GET /v1/images/{id}` 返回同一份 JSON。

| 状态 | 说明 |
|------|------|
| `queued` / `in_progress` | 还没完成，不返回 `data` |
| `completed` | 成功后返回 `data:[{ "url": "...", "revised_prompt": null }, …]`（可多张） |
| `failed` | 失败原因在 `error` |

同步完成的任务若你知道 `img_…` public id（例如从门户任务列表复制），也可用 `GET /v1/tasks/{id}` / `GET /v1/images/{id}` 查询；`data` 含全部转存后的图片。异步 worker 路径当前仍按单结果 URL 落一张。完整约定见[任务查询](/docs/tasks)。

---

*更新日期: 2026-08-26*

# 生视频

视频耗时长，对外强制异步。`POST` 立即返回任务（HTTP **200**，不是 202），不要阻塞到生成完成。后台生成等待至少约 60 分钟（按时长可更长，上限 2 小时）；超时对外 `failed`，不扣费。

**POST** `/v1/videos`

## 创建

请求体按 **Seedance / 方舟** 字段收。`duration` 与 `seconds` 同义，`ratio` 与 `aspect_ratio` 同义；同时出现时以前者为准。下表为推荐规范名；**snake_case 与 camelCase 均可**（如 `generate_audio` / `generateAudio`）。

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `model` | string | 是 | 对外 id |
| `prompt` | string | 是 | 文本。多模态参考里可用 `[Image 1]` / `[Video 1]` |
| `duration` | int ≥ 1 | 否 | 秒；默认 `5`。也可用 `seconds` |
| `ratio` | string | 否 | `16:9` / `9:16` / `1:1` / `4:3` / `3:4` / `21:9` / `adaptive`。也可用 `aspect_ratio` / `aspectRatio` |
| `resolution` | `480p` \| `720p` \| `1080p` \| `4k` | 否 | 短边档位。也可用 `resolution_name` / `resolutionName` |
| `size` | string | 否 | `1280x720` 会推成比例；`720p` 会当成 `resolution` |
| `generate_audio` | boolean | 否 | 同步配音（模型需支持）。也可用 `generateAudio` |
| `watermark` | boolean | 否 | 默认 `false` |
| `camera_fixed` | boolean | 否 | 固定机位。也可用 `cameraFixed` |
| `draft` | boolean | 否 | 草稿预览（1.5 Pro） |
| `seed` | int | 否 | 随机种子 |
| `first_frame` | string | 否 | 首帧 URL。也可用 `firstFrame`、`image.url`；完整别名见下表 |
| `last_frame` | string | 否 | 尾帧 URL，与首帧组成首尾帧。也可用 `lastFrame` |
| `reference_images` | string[] | 否 | 参考图，最多视模型（Seedance 2.0 最多 9）。也可用 `referenceImages`；完整别名见下表 |
| `reference_videos` | string[] | 否 | 参考视频。也可用 `referenceVideos`；完整别名见下表 |
| `reference_audio` | string[] | 否 | 参考音频。也可用 `referenceAudio`；完整别名见下表 |

### 媒体字段别名

图 / 音 / 视频参考下列字段名都认（含各自 camelCase / snake_case）。值可以是：

| 形态 | 说明 |
|------|------|
| **公网 URL** | `http://` / `https://` 字符串，或字符串数组，或 `{ "url": "..." }` |
| **Base64** | `data:*;base64,...`，或可识别为媒体的裸 base64；会先转存 |
| **文件流** | `multipart/form-data` 上传（如 `-F input_reference[]=@a.png`）；会先转存 |

**不支持**本机文件路径。单文件约 10MB，最多 9 个文件。

| 用途 | 规范字段 | 也认（写全） |
|------|----------|--------------|
| 首帧 / 单图 | `first_frame` | `firstFrame`、`first_frame_image`、`firstFrameImage`、`init_image`、`initImage`、`image_url`、`imageUrl`、`image`（字符串）、`file`、`input_image`、`inputImage` |
| 参考图 | `reference_images` | `referenceImages`、`reference_image`、`referenceImage`、`image_urls`、`imageUrls`、`images`、`input_reference`、`inputReference` |
| 尾帧 | `last_frame` | `lastFrame`、`last_frame_image`、`lastFrameImage` |
| 参考音频 | `reference_audio` | `referenceAudio`、`reference_audios`、`referenceAudios`、`audio_url`、`audioUrl`、`audio_urls`、`audioUrls`、`audio`、`audios`、`input_audio`、`inputAudio`、`voice`、`music` |
| 参考视频 | `reference_videos` | `referenceVideos`、`reference_video`、`referenceVideo`、`video_url`、`videoUrl`、`video_urls`、`videoUrls`、`video`、`videos`、`input_video`、`inputVideo`、`clip`、`clips` |

单独传一张图（如仅 `image_url`）会当作首帧；若已有 `reference_images` / 参考音视频，则同类别名并入参考素材。首尾帧与参考素材不要混用：有参考素材时，部分模型会忽略首尾帧语义。即梦类模型会尽量映射成 `image_urls`；音频 / 参考视频是否生效取决于所选模型。

计费按创建时写入的 `duration`（或 `seconds`，默认 5）与 `resolution`。配置了**价目表**的模型按 `mode` 查表：`per_second` 为单价 × 秒数，`per_resolution` 为分辨率一口价（与秒无关），`fixed` 为分辨率 × 秒数档位一口价；否则按单价 × 秒数，`resolution` / `size` / `ratio` 可能乘价格系数。

> **AI SDK generateVideo 对不上这条路径**
>
> `experimental_generateVideo` 走 ByteDance ModelArk / AI Gateway 的任务协议，不是本平台 `POST /v1/videos`。对客请 HTTP 调本接口，或继续用 OpenAI SDK 的对话/生图。本接口同时接受 snake_case 与 camelCase 字段名。

```bash
curl https://tokenmei.com/v1/videos \
  -H "Authorization: Bearer $MOMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_VIDEO_MODEL",
    "prompt": "镜头跟随橙猫穿过雨夜街道",
    "duration": 5,
    "ratio": "16:9",
    "resolution": "720p",
    "generate_audio": false
  }'
```

```javascript
const created = await fetch("https://tokenmei.com/v1/videos", {
  method: "POST",
  headers: {
    Authorization: \`Bearer \${process.env.MOMO_API_KEY}\`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "YOUR_VIDEO_MODEL",
    prompt: "镜头跟随橙猫穿过雨夜街道",
    duration: 5,
    ratio: "16:9",
    resolution: "720p",
    generate_audio: false,
  }),
}).then((res) => res.json());
console.log(created.id, created.status);
```

```python
import os, time, httpx

base = "https://tokenmei.com"
headers = {
    "Authorization": f"Bearer {os.environ['MOMO_API_KEY']}",
    "Content-Type": "application/json",
}
created = httpx.post(
    f"{base}/v1/videos",
    headers=headers,
    json={
        "model": "YOUR_VIDEO_MODEL",
        "prompt": "镜头跟随橙猫穿过雨夜街道",
        "duration": 5,
        "ratio": "16:9",
        "resolution": "720p",
        "generate_audio": False,
    },
).json()
print(created["id"], created["status"])
```

```go
body, _ := json.Marshal(map[string]any{
	"model":          "YOUR_VIDEO_MODEL",
	"prompt":         "镜头跟随橙猫穿过雨夜街道",
	"duration":       5,
	"ratio":          "16:9",
	"resolution":     "720p",
	"generate_audio": false,
})
req, _ := http.NewRequest("POST", "https://tokenmei.com/v1/videos", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+os.Getenv("MOMO_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
var created map[string]any
json.NewDecoder(res.Body).Decode(&created)
fmt.Println(created["id"], created["status"])
```

```php
$ch = curl_init("https://tokenmei.com/v1/videos");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("MOMO_API_KEY"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "model" => "YOUR_VIDEO_MODEL",
        "prompt" => "镜头跟随橙猫穿过雨夜街道",
        "duration" => 5,
        "ratio" => "16:9",
        "resolution" => "720p",
        "generate_audio" => false,
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$created = json_decode(curl_exec($ch), true);
echo $created["id"], " ", $created["status"], PHP_EOL;
```

```java
HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://tokenmei.com/v1/videos"))
    .header("Authorization", "Bearer " + System.getenv("MOMO_API_KEY"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString("""
        {
          "model": "YOUR_VIDEO_MODEL",
          "prompt": "镜头跟随橙猫穿过雨夜街道",
          "duration": 5,
          "ratio": "16:9",
          "resolution": "720p",
          "generate_audio": false
        }
        """))
    .build();
String body = HttpClient.newHttpClient().send(req, HttpResponse.BodyHandlers.ofString()).body();
System.out.println(body);
```

```csharp
using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("MOMO_API_KEY"));
var created = await http.PostAsJsonAsync("https://tokenmei.com/v1/videos", new {
    model = "YOUR_VIDEO_MODEL",
    prompt = "镜头跟随橙猫穿过雨夜街道",
    duration = 5,
    ratio = "16:9",
    resolution = "720p",
    generate_audio = false,
});
Console.WriteLine(await created.Content.ReadAsStringAsync());
```

创建响应：

```json
{
  "id": "video_a1b2c3d4e5f6",
  "object": "video",
  "model": "YOUR_VIDEO_MODEL",
  "status": "queued",
  "progress": 0,
  "created_at": 1710000000,
  "completed_at": null,
  "error": null
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | string | 前缀固定 `video_`，用于查询 |
| `object` | string | 固定 `video` |
| `model` | string | 对外模型 id |
| `status` | string | 见下方状态表 |
| `progress` | int | 0–100 |
| `created_at` | int | Unix 秒 |
| `completed_at` | int \| null | 未完成时为 `null` |
| `error` | string \| null | 成功为 `null`，失败为说明字符串，不是 `{ message }` 对象 |

用这个 id 去查询，推荐 `GET /v1/tasks/{id}`。`GET /v1/videos/{id}` 是同一查询的别名。

图生视频（首帧）：

```json
{
  "model": "YOUR_VIDEO_MODEL",
  "prompt": "猫转头看向镜头",
  "duration": 5,
  "first_frame": "https://cdn.example.com/frame.png"
}
```

首尾帧：

```json
{
  "first_frame": "https://cdn.example.com/first.png",
  "last_frame": "https://cdn.example.com/last.png"
}
```

多模态参考（Seedance 2.0）：

```json
{
  "prompt": "让 [Image 1] 的人物走在 [Video 1] 的街道上",
  "duration": 8,
  "ratio": "16:9",
  "reference_images": ["https://cdn.example.com/person.png"],
  "reference_videos": ["https://cdn.example.com/street.mp4"]
}
```

**GET** `/v1/tasks/{id}`

只能查**本租户**的任务。别人的 id 或未知 id：`404`（`code` 为 `model_not_found`，`param` 为 `id`）。余额为 0 时仍可 GET。`GET /v1/videos/{id}` 返回同一份 JSON。

客户可见 `status`：

| 对外 | 内部在做什么 |
|------|----------------|
| `queued` | 已受理 |
| `in_progress` | 生成中，或已生成正在转存（未关闭转存的模型） |
| `completed` | 生成完成，可取 `url` |
| `failed` | 失败或超时；`error` 为说明字符串 |

内部「转存中」对外仍是 `in_progress`，此时还没有 `url`；**生成成功后即已扣费**，转存失败不会退还。上架视频模型可以关闭「产物转存」，此时完成后直接返回上游视频地址；若上游需要鉴权或不是公网 HTTPS 链接，平台会自动回退转存。直链有效期由上游决定。`error` 成功时为 `null`，失败时是字符串，不是 `{ message }` 对象。

## 轮询

建议 2–5 秒一次，直到 `completed` 或 `failed`。不要用创建请求一直挂着等。图和视频共用 `GET /v1/tasks/{id}`，详见[任务查询](/docs/tasks)。

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

```javascript
async function waitForVideo(id) {
  for (;;) {
    const task = await fetch(\`https://tokenmei.com/v1/tasks/\${id}\`, {
      headers: { Authorization: \`Bearer \${process.env.MOMO_API_KEY}\` },
    }).then((res) => res.json());
    if (task.status === "completed") return task;
    if (task.status === "failed") throw new Error(task.error ?? "failed");
    await new Promise((resolve) => setTimeout(resolve, 3000));
  }
}
```

```python
import os, time, httpx

base = "https://tokenmei.com"
headers = {"Authorization": f"Bearer {os.environ['MOMO_API_KEY']}"}

def wait_for_video(video_id: str) -> dict:
    while True:
        task = httpx.get(f"{base}/v1/tasks/{video_id}", headers=headers).json()
        if task["status"] == "completed":
            return task
        if task["status"] == "failed":
            raise RuntimeError(task.get("error") or "failed")
        time.sleep(3)
```

```go
func waitForVideo(id string) (map[string]any, error) {
	for {
		req, _ := http.NewRequest("GET", "https://tokenmei.com/v1/tasks/"+id, nil)
		req.Header.Set("Authorization", "Bearer "+os.Getenv("MOMO_API_KEY"))
		res, _ := http.DefaultClient.Do(req)
		var task map[string]any
		json.NewDecoder(res.Body).Decode(&task)
		res.Body.Close()
		switch task["status"] {
		case "completed":
			return task, nil
		case "failed":
			return nil, fmt.Errorf("%v", task["error"])
		}
		time.Sleep(3 * time.Second)
	}
}
```

```php
function wait_for_video(string $id): array {
    while (true) {
        $ch = curl_init("https://tokenmei.com/v1/tasks/$id");
        curl_setopt_array($ch, [
            CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("MOMO_API_KEY")],
            CURLOPT_RETURNTRANSFER => true,
        ]);
        $task = json_decode(curl_exec($ch), true);
        if ($task["status"] === "completed") return $task;
        if ($task["status"] === "failed") throw new RuntimeException($task["error"] ?? "failed");
        sleep(3);
    }
}
```

```java
Map<String, Object> waitForVideo(String id) throws Exception {
    HttpClient http = HttpClient.newHttpClient();
    while (true) {
        HttpRequest req = HttpRequest.newBuilder()
            .uri(URI.create("https://tokenmei.com/v1/tasks/" + id))
            .header("Authorization", "Bearer " + System.getenv("MOMO_API_KEY"))
            .GET()
            .build();
        String body = http.send(req, HttpResponse.BodyHandlers.ofString()).body();
        JsonObject task = JsonParser.parseString(body).getAsJsonObject();
        String status = task.get("status").getAsString();
        if ("completed".equals(status)) return Map.of("task", task);
        if ("failed".equals(status)) throw new IllegalStateException(String.valueOf(task.get("error")));
        Thread.sleep(3000);
    }
}
```

```csharp
async Task<JsonElement> WaitForVideo(string id) {
    using var http = new HttpClient();
    http.DefaultRequestHeaders.Authorization =
        new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("MOMO_API_KEY"));
    while (true) {
        var task = await http.GetFromJsonAsync<JsonElement>($"https://tokenmei.com/v1/tasks/{id}");
        var status = task.GetProperty("status").GetString();
        if (status == "completed") return task;
        if (status == "failed") throw new Exception(task.GetProperty("error").ToString());
        await Task.Delay(3000);
    }
}
```

完成后：

```json
{
  "id": "video_a1b2c3d4e5f6",
  "object": "video",
  "model": "YOUR_VIDEO_MODEL",
  "status": "completed",
  "progress": 100,
  "created_at": 1710000000,
  "completed_at": 1710000120,
  "error": null,
  "url": "https://cdn.example.com/v/xxx.mp4",
  "usage": {
    "seconds": 5,
    "cost": { "amount": "0.5000", "currency": "CNY" }
  }
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `url` | string | 视频结果地址，仅 `completed` 时出现；默认是平台转存后的稳定地址，关闭转存的模型可能直接是上游地址 |
| `usage.seconds` | int | 计费秒数，取创建时的 `duration` / `seconds` |
| `usage.cost` | object | 可选，对外售价 |

**GET** `/v1/videos/{id}/content`

任务未完成时 `404`（同样是 `model_not_found` / `param=id`）。完成后：

| `Accept` | 结果 |
|----------|------|
| `application/json` | `{ "url": "..." }` |
| 其他 | `302` 到结果地址（平台稳定地址或上游地址） |

```bash
curl -L https://tokenmei.com/v1/videos/video_a1b2c3d4e5f6/content \
  -H "Authorization: Bearer $MOMO_API_KEY" \
  -o clip.mp4

curl https://tokenmei.com/v1/videos/video_a1b2c3d4e5f6/content \
  -H "Authorization: Bearer $MOMO_API_KEY" \
  -H "Accept: application/json"
```

```javascript
const res = await fetch("https://tokenmei.com/v1/videos/video_a1b2c3d4e5f6/content", {
  headers: {
    Authorization: \`Bearer \${process.env.MOMO_API_KEY}\`,
    Accept: "application/json",
  },
  redirect: "manual",
});
console.log(await res.json());
```

```python
import os, httpx

headers = {"Authorization": f"Bearer {os.environ['MOMO_API_KEY']}"}
print(httpx.get(
    "https://tokenmei.com/v1/videos/video_a1b2c3d4e5f6/content",
    headers={**headers, "Accept": "application/json"},
).json())
open("clip.mp4", "wb").write(httpx.get(
    "https://tokenmei.com/v1/videos/video_a1b2c3d4e5f6/content",
    headers=headers,
    follow_redirects=True,
).content)
```

```go
req, _ := http.NewRequest("GET", "https://tokenmei.com/v1/videos/video_a1b2c3d4e5f6/content", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("MOMO_API_KEY"))
req.Header.Set("Accept", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
io.Copy(os.Stdout, res.Body)
```

```php
$ch = curl_init("https://tokenmei.com/v1/videos/video_a1b2c3d4e5f6/content");
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("MOMO_API_KEY"),
        "Accept: application/json",
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
echo curl_exec($ch);
```

```java
HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://tokenmei.com/v1/videos/video_a1b2c3d4e5f6/content"))
    .header("Authorization", "Bearer " + System.getenv("MOMO_API_KEY"))
    .header("Accept", "application/json")
    .GET()
    .build();
System.out.println(HttpClient.newHttpClient().send(req, HttpResponse.BodyHandlers.ofString()).body());
```

```csharp
using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("MOMO_API_KEY"));
http.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
Console.WriteLine(await http.GetStringAsync("https://tokenmei.com/v1/videos/video_a1b2c3d4e5f6/content"));
```

> **未完成不要当成功**
>
> 没有 `url` 时不要给终端用户播放。生成成功后即扣费；转存失败对外是 `failed`，不会在转存失败时返回临时结果链。关闭转存的模型返回的上游地址可能过期，建议拿到后尽快下载或自行转存。

---

*更新日期: 2026-08-25*

# 任务查询

图和视频共用一条轮询路径。创建仍走各自接口，拿到 `id` 后都用这里查进度。

**GET** `/v1/tasks/{id}`

`{id}` 就是创建响应里的 id：生图异步为 `img_…`，生视频为 `video_…`。只能查**本租户**的任务。别人的 id 或未知 id：`404`（`code` 为 `model_not_found`，`param` 为 `id`）。余额为 0 时仍可 GET。这条路径不计 RPM。

创建：

- 生图：`POST /v1/images/generations` — `async: true` 时立即返回任务 id；**默认同步**也会落任务记录（门户/管理端任务列表可见），同步成功体不含 `id`
- 生视频：`POST /v1/videos`，始终返回任务 id

> **资源路径仍可用**
>
> `GET /v1/images/{id}`、`GET /v1/videos/{id}` 与本接口返回同一份 JSON，作为别名保留。新接入请用 `/v1/tasks/{id}`。取视频文件仍走 `GET /v1/videos/{id}/content`。

## 公共字段

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | string | 任务对外 id：生图 `img_…`，生视频 `video_…` |
| `object` | string | `image` 或 `video`，决定完成后的结果形状 |
| `model` | string | 对外模型 id |
| `status` | string | 见下表 |
| `progress` | int | 0–100 |
| `created_at` | int | Unix 秒 |
| `completed_at` | int \| null | 未完成时为 `null` |
| `error` | string \| null | 成功为 `null`，失败为说明字符串 |

客户可见 `status`：

| 对外 | 内部在做什么 |
|------|----------------|
| `queued` | 已受理 |
| `in_progress` | 生成中，或已生成正在转存（未关闭转存的模型） |
| `completed` | 生成完成，可取结果 URL |
| `failed` | 失败或超时；`error` 为说明字符串 |

内部「转存中」对外仍是 `in_progress`，此时还没有结果 URL；**生成成功后即已扣费**，转存失败不会退还。视频模型可关闭产物转存，完成后直接返回上游地址（无法安全直出时自动回退转存）。

## 轮询

建议 2–5 秒一次，直到 `completed` 或 `failed`。不要用创建请求一直挂着等。

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

```javascript
async function waitForTask(id) {
  for (;;) {
    const task = await fetch(\`https://tokenmei.com/v1/tasks/\${id}\`, {
      headers: { Authorization: \`Bearer \${process.env.MOMO_API_KEY}\` },
    }).then((res) => res.json());
    if (task.status === "completed") return task;
    if (task.status === "failed") throw new Error(task.error ?? "failed");
    await new Promise((resolve) => setTimeout(resolve, 3000));
  }
}
```

```python
import os, time, httpx

base = "https://tokenmei.com"
headers = {"Authorization": f"Bearer {os.environ['MOMO_API_KEY']}"}

def wait_for_task(task_id: str) -> dict:
    while True:
        task = httpx.get(f"{base}/v1/tasks/{task_id}", headers=headers).json()
        if task["status"] == "completed":
            return task
        if task["status"] == "failed":
            raise RuntimeError(task.get("error") or "failed")
        time.sleep(3)
```

```go
func waitForTask(id string) (map[string]any, error) {
	for {
		req, _ := http.NewRequest("GET", "https://tokenmei.com/v1/tasks/"+id, nil)
		req.Header.Set("Authorization", "Bearer "+os.Getenv("MOMO_API_KEY"))
		res, _ := http.DefaultClient.Do(req)
		var task map[string]any
		json.NewDecoder(res.Body).Decode(&task)
		res.Body.Close()
		switch task["status"] {
		case "completed":
			return task, nil
		case "failed":
			return nil, fmt.Errorf("%v", task["error"])
		}
		time.Sleep(3 * time.Second)
	}
}
```

```php
function wait_for_task(string $id): array {
    while (true) {
        $ch = curl_init("https://tokenmei.com/v1/tasks/$id");
        curl_setopt_array($ch, [
            CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("MOMO_API_KEY")],
            CURLOPT_RETURNTRANSFER => true,
        ]);
        $task = json_decode(curl_exec($ch), true);
        if ($task["status"] === "completed") return $task;
        if ($task["status"] === "failed") throw new RuntimeException($task["error"] ?? "failed");
        sleep(3);
    }
}
```

```java
JsonObject waitForTask(String id) throws Exception {
    HttpClient http = HttpClient.newHttpClient();
    while (true) {
        HttpRequest req = HttpRequest.newBuilder()
            .uri(URI.create("https://tokenmei.com/v1/tasks/" + id))
            .header("Authorization", "Bearer " + System.getenv("MOMO_API_KEY"))
            .GET()
            .build();
        JsonObject task = JsonParser.parseString(
            http.send(req, HttpResponse.BodyHandlers.ofString()).body()
        ).getAsJsonObject();
        String status = task.get("status").getAsString();
        if ("completed".equals(status)) return task;
        if ("failed".equals(status)) throw new IllegalStateException(String.valueOf(task.get("error")));
        Thread.sleep(3000);
    }
}
```

```csharp
async Task<JsonElement> WaitForTask(string id) {
    using var http = new HttpClient();
    http.DefaultRequestHeaders.Authorization =
        new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("MOMO_API_KEY"));
    while (true) {
        var task = await http.GetFromJsonAsync<JsonElement>($"https://tokenmei.com/v1/tasks/{id}");
        var status = task.GetProperty("status").GetString();
        if (status == "completed") return task;
        if (status == "failed") throw new Exception(task.GetProperty("error").ToString());
        await Task.Delay(3000);
    }
}
```

## 完成后：视频

`object` 为 `video`。结果在 `url`。

```json
{
  "id": "video_a1b2c3d4e5f6",
  "object": "video",
  "model": "YOUR_VIDEO_MODEL",
  "status": "completed",
  "progress": 100,
  "created_at": 1710000000,
  "completed_at": 1710000120,
  "error": null,
  "url": "https://cdn.example.com/v/xxx.mp4",
  "usage": {
    "seconds": 5,
    "cost": { "amount": "0.5000", "currency": "CNY" }
  }
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `url` | string | 视频结果地址：默认是平台转存后的稳定地址；关闭转存的模型可能直接返回上游地址 |
| `usage.seconds` | int | 计费秒数 |
| `usage.cost` | object | 可选，对外售价 |

## 完成后：生图

`object` 为 `image`。结果在 `data`（与同步生图一致）。同步多图会返回全部转存 URL；异步 worker 路径当前按单结果 URL 落一张。

```json
{
  "id": "img_a1b2c3d4e5f6",
  "object": "image",
  "model": "YOUR_IMAGE_MODEL",
  "status": "completed",
  "progress": 100,
  "created_at": 1710000000,
  "completed_at": 1710000060,
  "error": null,
  "data": [
    { "url": "https://cdn.example.com/a/xxx.png", "revised_prompt": null }
  ],
  "usage": {
    "images_generated": 1,
    "cost": { "amount": "0.2200", "currency": "CNY" }
  }
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `data` | array | 与同步生图一致；同步可多张，异步 worker 当前多为单张 |
| `data[].url` | string | 转存后的稳定地址 |
| `data[].revised_prompt` | null | 固定为 `null` |
| `usage.images_generated` | int | 实际张数 |
| `usage.cost` | object | 可选，对外售价 |

> **未完成不要当成功**
>
> 没有结果 URL 时不要给终端用户展示。生成成功后即扣费；转存失败对外是 `failed`，不会返回临时结果链。

---

*更新日期: 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)

---

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

# 错误码

所有 `/v1` 错误都是同一形状：

```json
{
  "error": {
    "message": "Model seedream-x is not available",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found"
  }
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `error.message` | string | 可读说明，可能改文案，不要当稳定契约 |
| `error.type` | string | OpenAI 风格分类：`authentication_error` / `rate_limit_error` / `invalid_request_error` / `api_error` |
| `error.param` | string \| null | 出错字段，例如 `model`、`id` |
| `error.code` | string | 业务逻辑看这个 |

业务逻辑看 `code`。响应**不包含** `Retry-After`。

| code | HTTP | type | 何时 |
|------|------|------|------|
| `invalid_api_key` | 401 | authentication_error | 缺 Key、错 Key、已吊销、租户停用 |
| `insufficient_quota` | 429 | rate_limit_error | 余额不足且方法不是 GET（`/v1/sub-accounts` 管理面除外）。`GET /v1/balance` 在余额为 0 时仍是 200，`balance` 为 `"0.00"` |
| `management_forbidden` | 403 | invalid_request_error | 用子账户 Key 调用 `/v1/sub-accounts` 管理接口 |
| `rate_limit_exceeded` | 429 | rate_limit_error | 该 Key 该能力超过 RPM |
| `invalid_request` | 400 | invalid_request_error | 请求体校验失败（缺字段、类型不对） |
| `model_not_found` | 404 | invalid_request_error | 模型不可用；任务不存在；视频未完成时取 content |
| `capability_not_enabled` | 400 | invalid_request_error | 模型能力与路径不符，或该能力未实现 |
| `upstream_error` | 502 | api_error | 模型服务失败或转存失败；不透出原始错误细节 |
| `upstream_unavailable` | 503 / 400 | api_error 或 invalid_request_error | 服务暂不可用，或当前无法完成请求 |
| `gateway_timeout` | 504 | api_error | 网关等待模型服务超时，未扣费 |
| `content_policy_violation` | 400 | invalid_request_error | 内容策略拒绝（若映射到此码）；多数情况下仍表现为 `upstream_error` |

## 对话流里的错误

`stream: true` 时，模型调用失败可能仍是 HTTP 200。事件流里会出现：

```
data: {"error":{"message":"模型服务请求失败","type":"api_error","param":null,"code":"upstream_error"}}

data: [DONE]
```

解析 SSE 时先看有没有 `error`，再拼 `delta.content`。

## 转存失败

图/视频生成成功但对象存储写入失败时，对外仍是 `upstream_error`，`message` 为「转存失败」，不会把临时链接交给你。视频模型关闭产物转存时不走对象存储，会直接返回上游地址；若无法安全直出则自动回退转存。

> **重试**
>
> `gateway_timeout`、偶发 `upstream_error` 可以有限重试。`invalid_api_key`、`invalid_request`、`model_not_found`、`capability_not_enabled` 重试无意义。`insufficient_quota` 要等充值。`rate_limit_exceeded` 等下一自然分钟窗口。

---

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

# 计费与产物

币种固定 `CNY`。单价见 `GET /v1/models` 里的 `pricing`。

## 什么时候扣

| 能力 | 成功条件 | 计量 |
|------|----------|------|
| 对话 | 非流式成功返回；流式在 `[DONE]` 前写完 usage 且流正常结束 | 实际 `prompt_tokens` + `completion_tokens` |
| 生图 | 同步成功 | `data.length`（至少按 1 张） |
| 视频 | 状态 `completed`（转存后或直出上游地址） | 创建时的 `duration` 或 `seconds`（默认 5） |

失败、超时、策略拒绝不扣费。发请求前会按估算占用余额，失败或未完成时释放；长任务以终态实扣为准。没有自动退款接口。

分辨率 `size` 可能乘系数，以模型目录里的定价为准。对话按百万 token 分别设置输入、输出单价。

## `usage.cost`

成功响应里可能有：

```json
"cost": { "amount": "0.0021", "currency": "CNY" }
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `amount` | string | 本次扣费金额 |
| `currency` | string | 固定 `CNY` |

`cost` 是可选字段，有时不会返回。解析时按可选处理。

各能力 `usage` 其余字段：

| 能力 | 字段 |
|------|------|
| 对话 | `prompt_tokens` / `completion_tokens` / `total_tokens` |
| 生图 | `images_generated` |
| 视频 | `seconds`（仅 `completed` 时出现） |

## 查询余额

**GET** `/v1/balance`

无请求体，也没有查询参数。鉴权与其它 `/v1` 相同。不计费，不占对话 / 生图 / 生视频 RPM。余额为 0 或为负时，这个 GET 仍返回 200，不会变成 `insufficient_quota`。

返回的是**当前这把 Key 还能花的余额**，进行中的占用已经扣掉：

- 主账户 Key：主账户余额，`scope` 为 `tenant`
- 子账户 Key：该子账户额度，`scope` 为 `sub_account`，看不到主账户余额

```bash
curl $BASE/v1/balance \
  -H "Authorization: Bearer $MOMO_API_KEY"
```

主账户 Key：

```json
{
  "object": "balance",
  "balance": "12.50",
  "currency": "CNY",
  "scope": "tenant"
}
```

子账户 Key：

```json
{
  "object": "balance",
  "balance": "3.20",
  "currency": "CNY",
  "scope": "sub_account"
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `object` | string | 固定 `balance` |
| `balance` | string | 固定两位小数，多余位数向下取整 |
| `currency` | string | 固定 `CNY` |
| `scope` | string | `tenant` 或 `sub_account` |

`balance` 示例：`12.5` → `"12.50"`，`12.599` → `"12.59"`，`0.009` → `"0.00"`，`-1.231` → `"-1.24"`。

实际扣费仍按更高精度记账。`usage.cost.amount`、子账户划拨 `amount`、以及 `/v1/sub-accounts` 里的 `quota_balance` 都不是这个两位截断。所以实际余额还有 `0.009` 时，这里会显示 `"0.00"`，但生成请求仍按实际余额判断：大于 0 就不会因为显示成 `"0.00"` 被拒绝。

Key 无效、已吊销，或账户停用：`401` + `invalid_api_key`。

## 产物 URL

图（`url` 模式）和视频默认会先转存到平台存储，再返回稳定路径。URL 有保留期，过期后会失效。请当作短期可访问地址缓存，不要假设永久。上架视频模型可以关闭产物转存，此时视频 `url` 可能直接指向上游，有效期由上游决定；无法安全直出时会自动回退转存。

`b64_json` 图片仍会写入平台存储（响应返回 base64），对话文本不转存。Prompt 不会在响应里回显原文。

> **余额为 0**
>
> 不能再 `POST` 生成，但 `GET /v1/models`、`GET /v1/balance` 和 `GET /v1/tasks/{id}` 仍可用。

子账户有独立 `quota_balance`：用子账户 Key 调生成时只扣该额度；主账户可用 `/v1/sub-accounts` 划拨 / 收回，见 [子账户](/docs/sub-accounts)。

---

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

# 超时与限制

对接时按下面的上限设客户端超时，不要用 OpenAI 默认的几十秒去等生图/视频。

## 网关等待

| 场景 | 上限 | 超时表现 |
|------|------|----------|
| 普通 HTTP（对话非流式、生图同步等待） | 5 分钟 | `504` `gateway_timeout`，不扣费 |
| 对话 SSE | 最长 600 秒（OpenAI 兼容流式） | 流中断；是否扣费看流有没有正常结束 |
| 视频任务 | 创建立即返回；后台生成等待至少约 **60 分钟**（按时长可更长，上限 2 小时） | 对外 `failed`，不扣费 |

客户端建议：对话非流式 130s，流式 10 分钟，生图 130s，视频创建 30s、轮询总时长 16 分钟。

## 限流与额度

默认 RPM（可被运营改成 Key 自己的，空则继承租户）：对话 120、生图 60、创建视频 20。按「Key × 能力 × 自然分钟」计数。只有带能力标签的 `POST` 会计数；`GET /v1/models`、`GET /v1/balance` 和任务查询不计 RPM。

余额 ≤ 0：非 GET 返回 `insufficient_quota`；轮询任务、列模型、查余额仍可用。

## 请求体

- `Content-Type: application/json`（SSE 响应除外）。
- 未知字段会被丢掉，不会 400。不要靠多传字段「试探能力」。
- `messages` 至少一条；`n`、`duration` / `seconds` 必须 ≥ 1。
- 校验失败（缺字段、类型不对）是 `400` + `invalid_request`。

## 对外 id

| 能力 | 出现位置 | 前缀 |
|------|----------|------|
| 对话 | 成功响应 / SSE 帧的 `id` | `chatcmpl_` |
| 生图任务 | 异步创建响应 / 任务查询；同步也会落库（门户任务列表） | `img_` |
| 视频 | 创建与查询响应的 `id` | `video_` |

同步生图成功体没有对外 `id`（仍是 `{ created, data, usage }`）。异步生图和视频创建返回的 `id` 就是 `GET /v1/tasks/{id}` 用的任务 id。同步生图的 `img_…` 可在门户/管理端任务列表看到，也可用该 id 查询。
