*更新日期: 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) 确认路径与字段是否支持。
