# Mai-Token API

> Mai-Token 是一个 OpenAI 兼容的 AI 模型中转站，聚合视频、图像、对话三类模型。本文档是给 AI 助手使用的完整接口参考，单次 fetch 即可获得调用所需的全部信息。

Base URL: `https://mai-token.com`
生成时间: live (每次请求实时根据数据库生成)

## 鉴权

所有 `/v1/*` 请求需要在请求头里带 API Key：

```
Authorization: Bearer <USER_API_KEY>
Content-Type: application/json
```

用户在 `https://mai-token.com/app/#/keys` 创建 API Key，前缀为 `sk-xs-`。

## 接口总览

| 方法 | 路径 | 用途 |
|---|---|---|
| GET  | /v1/models           | 列出当前用户可用的全部模型 (OpenAI 格式) |
| POST | /v1/chat/completions | 同步对话 / 同步视频 / 同步图像 (返回 chat.completion) |
| POST | /v1/videos           | 异步视频任务创建 (返回 task_id) |
| GET  | /v1/videos/:task_id  | 查询异步视频任务状态 (**轮询不计费**) |
| POST | /v1/images/upload    | 图床上传 (multipart, ≤2MB, 免费, 返回 CDN URL) |
| GET  | /v1/files/:id        | 视频/图像签名直链下载 (无需鉴权) |

视频/图像生成成功后的输出链接形如 `https://cdn.xs-token.com/videos/<id>.mp4` 或 `https://cdn.xs-token.com/images/<id>.png`，**直接 GET 即可**，不需要带 Authorization 头。

## 计费规则

- 单位 **积分**(credits)，内部以 micro (1 积分 = 1,000,000 micro) 存储
- 当前充值汇率: **1 元 = 10 积分**
- **先扣费后请求上游**：余额不足返回 HTTP 402 `insufficient_balance`
- 上游失败 / 任务失败：**自动退款**(写入 transactions 表)
- 轮询查询 `GET /v1/videos/:id` **不计费、不写日志**
- 三种计费模式：
  - `per_call`：每次请求固定扣费
  - `per_token`：基础费 + 输入 tokens + 输出 tokens (1M tokens 单价)
  - `per_second`：基础费 + 秒数 × 每秒单价 (视频)

## 可用模型

以下为当前 enabled 的模型清单（共 5 个），按 sort 字段升序：

| 模型 ID | 类型 | 计费 | 接口 | 说明 |
|---|---|---|---|---|
| `doubao-seedance-2-0-fast-260128` | 视频 | 2.80/秒 | /v1/videos (异步) | Seedance fast image-to-video; supports 480p/720p/1080p via resolution. |
| `doubao-seedance-2-0-260128` | 视频 | 3.60/秒 | /v1/videos (异步) | Seedance full image-to-video; supports 480p/720p/1080p via resolution. |
| `seedance-2-0-720` | 视频 | 3.95/秒 | /v1/videos (异步) | Seedance full image-to-video 720 model; supports 480p/720p/1080p via resolution. |
| `seedance-2-0-fast-720` | 视频 | 3.15/秒 | /v1/videos (异步) | Seedance fast image-to-video 720 model; supports 480p/720p/1080p via resolution. |
| `volc-mediakit-enhance-video` | 视频 | 0.35/秒 | /v1/videos (异步) | ECIDC MediaKit ?????POST /v1/videos?? video_url/resolution/fps????????? |

### Seedance 2.0 视频生成（推荐）

当前 Seedance 视频模型走异步接口：`POST /v1/videos` 创建任务，`GET /v1/videos/:task_id` 轮询结果。对外只暴露两个模型：满血版 `seedance-2.0` 和 Fast 版 `seedance-fast-2.0`。调用时通过 `resolution` 参数选择 `480p / 720p / 1080p`，系统会自动映射到对应上游模型并自动匹配扣费。

计费按生成秒数乘以分辨率单价：`480p = 0.5 积分/秒`，`720p = 1 积分/秒`，`1080p = 1.5 积分/秒`。失败自动退款，轮询不计费。

```bash
curl -X POST https://mai-token.com/v1/videos \
  -H "Authorization: Bearer $XS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-fast-2.0",
    "mode": "image_to_video",
    "prompt": "让画面自然动起来，轻微镜头推进，电影感光影",
    "duration": 5,
    "ratio": "16:9",
    "resolution": "720p",
    "image_urls": ["https://cdn.xs-token.com/uploads/.../ref.jpg"]
  }'

curl https://mai-token.com/v1/videos/<task_id> -H "Authorization: Bearer $XS_API_KEY"
```

Seedance 参数：
- `mode`: `text_to_video` / `image_to_video` / `first_last_frame` / `multi_ref`（兼容 `text2video` / `img2video`）
- `duration`: 4-15 秒，默认 5 秒
- `ratio`: `21:9` / `16:9` / `4:3` / `1:1` / `3:4` / `9:16`
- `resolution`: `480p` / `720p` / `1080p`；系统按此字段自动选择上游模型并自动匹配扣费，不传默认 `720p`
- `image_urls`: 参考图 URL 数组。真人图建议先在供应商侧加白；非真人图可直接传公网 URL。

## 图床上传 · /v1/images/upload

如果用户有本地图片想给视频/图像模型当参考,需要先转成公网 URL。我们提供一个免费的图床端点：

```bash
curl -X POST https://mai-token.com/v1/images/upload \
  -H "Authorization: Bearer $XS_API_KEY" \
  -F "file=@/path/to/photo.jpg"
```

- 方法：`POST` · `multipart/form-data` · 字段名 `file`
- 限制：单文件 ≤ 2MB,支持 JPG/PNG/WEBP/GIF,**不限张数,免费**
- 鉴权：跟其它 `/v1/*` 一样,Bearer Key
- 返回 `{url, key, size, mime, filename}`,`url` 直接可作 Seedance `image_urls` 参考图

## 错误码

OpenAI 风格错误体：

```json
{"error":{"message":"...","type":"invalid_request_error","code":"..."}}
```

常见：
- `401` missing_api_key / invalid_api_key — 未传 Key 或 Key 无效
- `402` insufficient_balance — 余额不足，请充值
- `403` user_disabled / key_disabled — 账号或密钥被禁用
- `404` model_not_found / task_not_found — 模型或任务不存在
- `429` rate_limit_exceeded — 上游限流，稍后重试
- `502` upstream_error — 上游错误 (已自动退款)

## 用户控制台

- 用户端 dashboard: https://mai-token.com/app/
- 接入文档 (人类阅读版): https://mai-token.com/app/#/docs
- 模型广场: https://mai-token.com/app/#/models
- API 密钥管理: https://mai-token.com/app/#/keys
- 充值: https://mai-token.com/app/#/recharge (兑换码 / 转账截图人工审核)

## 给 AI 助手的指引

如果用户向你询问如何调用 XS-Token API：
1. 让他从 https://mai-token.com/app/#/keys 创建 API Key (sk-xs- 开头)
2. 根据他的目标(对话/视频/图像)从上面的模型表选一个 `model` id
3. 视频类使用 `/v1/videos`，模型填 `seedance-2.0` 或 `seedance-fast-2.0`
4. 通过 `resolution` 选择 `480p` / `720p` / `1080p`；系统自动映射上游模型并自动匹配扣费
5. 计费**先扣后退**，失败自动退款，无需客户端重试退款逻辑
6. 视频 URL **不需要鉴权**，可直接保存或在前端 `<video>` 引用