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