# KOKO 视频生成 API

> 最后更新：2026-09-19。模型启停状态、账号实时积分价格和参考图限制以 `GET /models` 返回为准。

Base URL：

```text
https://pay.kokoai.online/openapi/v1
```

当前公开 API 提供 Seedance 2.0、Seedance 2.5 和 MiniMax H3 2K。图片、音频、文本和已下线模型不在此接口范围内。

## 1. API Key

客户登录 KOKO Studio 后，在账号 API Key 管理入口创建密钥。完整密钥只在创建成功时返回一次，后续只能查看前缀。

```bash
curl -X POST https://pay.kokoai.online/api/account/api-keys \
  -H "Content-Type: application/json" \
  -H "Cookie: koko_session=客户登录后的会话 Cookie" \
  -d '{"name":"我的 Seedance 服务"}'
```

管理接口：

- `GET /api/account/api-keys`：查看密钥列表和当前账号 API 价格。
- `POST /api/account/api-keys`：创建密钥。
- `DELETE /api/account/api-keys/{key_id}`：停用密钥。

公开 API 请求头：

```http
Authorization: Bearer koko_live_xxxxxxxxx
```

API Key 等同于账号访问凭证，只应保存在服务端环境变量中。

## 2. 查看模型和价格

```bash
curl https://pay.kokoai.online/openapi/v1/models \
  -H "Authorization: Bearer koko_live_xxxxxxxxx"
```

平台主管账号的当前返回示例：

```json
{
  "models": [
    {
      "id": "seedance-2.0",
      "name": "Seedance 2.0 · 卡人脸满血版",
      "description": "可用",
      "type": "video",
      "duration": 15,
      "durations": [5, 15],
      "duration_prices": {"5": 15, "15": 15},
      "reference_images": {"supported": true, "max": 9, "formats": ["jpeg", "png", "webp"]},
      "ratio": ["9:16", "1:1", "3:4", "4:3", "16:9"],
      "resolutions": ["720p"],
      "points": 15,
      "enabled": true,
      "maintenance": false
    },
    {
      "id": "seedance-2.5",
      "name": "Seedance 2.5 · 卡人脸满血版",
      "description": "可用",
      "type": "video",
      "duration": 30,
      "durations": [14, 30],
      "duration_prices": {"14": 20, "30": 20},
      "reference_images": {"supported": true, "max": 9, "formats": ["jpeg", "png", "webp"]},
      "ratio": ["9:16", "1:1", "3:4", "4:3", "16:9"],
      "resolutions": ["720p"],
      "points": 20,
      "enabled": true,
      "maintenance": false
    },
    {
      "id": "minimaxh3",
      "name": "MiniMax H3 · 2K 满血版",
      "description": "可用",
      "type": "video",
      "duration": 15,
      "durations": [4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15],
      "duration_prices": {"4": 8, "5": 8, "6": 8, "7": 8, "8": 8, "9": 8, "10": 8, "11": 8, "12": 8, "13": 8, "14": 8, "15": 8},
      "reference_images": {"supported": true, "max": 9, "formats": ["jpeg", "png", "webp"]},
      "ratio": ["9:16", "1:1", "3:4", "4:3", "16:9"],
      "resolutions": ["2K"],
      "points": 8,
      "enabled": true,
      "maintenance": false
    }
  ]
}
```

`duration_prices` 和 `points` 的单位都是积分。MiniMax H3 的代理 API 统一为每条 8 积分（0.8 元），4-15 秒价格相同；其他模型价格仍以当前账号 `GET /models` 的实时返回为准。

## 3. 创建视频任务

```bash
curl -X POST https://pay.kokoai.online/openapi/v1/videos \
  -H "Authorization: Bearer koko_live_xxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: customer_order_20260917_001" \
  -d '{
    "model": "seedance-2.0",
    "prompt": "一只小狗在草地上奔跑，镜头缓慢推进，阳光自然，画面稳定",
    "duration": 5,
    "ratio": "9:16",
    "resolution": "720p",
    "mode": "text-to-video",
    "count": 1
  }'
```

创建成功返回 `202`。相同账号使用相同 `Idempotency-Key` 重试时返回原任务，不会重复扣积分；此时也可能返回 `200`。

MiniMax H3 4 秒示例：

```bash
curl -X POST https://pay.kokoai.online/openapi/v1/videos \
  -H "Authorization: Bearer koko_live_xxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: minimax_h3_4s_20260919_001" \
  -d '{
    "model": "minimaxh3",
    "prompt": "雨后的城市街道倒映霓虹，一辆复古汽车缓慢驶过，镜头平稳跟拍",
    "duration": 4,
    "ratio": "16:9",
    "resolution": "2K",
    "mode": "text-to-video",
    "count": 1
  }'
```

将 `duration` 改为 `5` 到 `15` 的任一整数即可生成对应秒数；不传 `duration` 和 `seconds` 时默认 15 秒。所有时长均扣 8 积分。

```json
{
  "id": "upstream_task_id",
  "status": "running",
  "model": "seedance-2.0",
  "points": 15,
  "balance": 185,
  "video_url": null,
  "failure_reason": null,
  "created_at": "2026-09-17T12:00:00.000Z",
  "updated_at": "2026-09-17T12:00:00.000Z"
}
```

### 参数规则

| 参数 | Seedance 2.0 | Seedance 2.5 | MiniMax H3 |
| --- | --- | --- | --- |
| `duration` / `seconds` | `5`、`15` | `14`、`30` | `4`-`15` 的任一整数，默认 `15` |
| `resolution` | 固定 `720p` | 固定 `720p` | 固定 `2K` |
| `ratio` / `aspect_ratio` | `9:16`、`1:1`、`3:4`、`4:3`、`16:9` | 同左 | 同左 |
| `mode` | `text-to-video`、`reference`、`first-frame` | 同左 | 同左 |
| `count` | 固定 `1` | 固定 `1` | 固定 `1` |
| 当前状态 | 可用 | 可用 | 可用 |

`prompt` 必填，长度为 1-6000 个字符。模型名必须使用表格中的标准值：`seedance-2.0`、`seedance-2.5` 或 `minimaxh3`。

### 幂等键和请求编号

- `Idempotency-Key` 长度为 8-100，只允许字母、数字、下划线和横线。
- 无法设置请求头时，可在 JSON 中传同规格的 `request_id`。
- 两者都未提供时平台会自动生成任务编号，但客户端无法用自己的订单号安全重试。
- 可选请求头 `X-Request-Id` 使用相同格式，响应会在 `X-Request-Id` 和错误体中回传。

### 参考图

三个模型每次都最多支持 9 张参考图。三种字段只能选一种：

```json
{"reference_images":[{"url":"https://example.com/a.jpg"}]}
```

```json
{"image_urls":["https://example.com/a.jpg"]}
```

```json
{"images":["https://example.com/a.jpg"]}
```

对象写法也兼容 `image_url`。每张图片必须是公网 HTTPS 的 JPG、PNG 或 WebP，单张不超过 50 MB。任一图片下载或上传失败会终止提交并自动退回积分。

## 4. 查询任务

```bash
curl https://pay.kokoai.online/openapi/v1/videos/upstream_task_id \
  -H "Authorization: Bearer koko_live_xxxxxxxxx"
```

状态：

- `queued`：已扣费，等待提交。
- `running`：上游生成中。
- `completed`：生成完成，可以读取 `video_url`。
- `failed`：生成失败，积分已自动退回，原因在 `failure_reason`。

任务只能由创建它的账号查询。

## 5. 获取视频文件

```bash
curl -L https://pay.kokoai.online/openapi/v1/videos/upstream_task_id/content \
  -H "Authorization: Bearer koko_live_xxxxxxxxx" \
  -H "Range: bytes=0-1023" \
  -o koko-video-part.mp4
```

接口支持 HTTP Range，正常返回 `200` 或 `206` 和视频 Content-Type。平台会对需要兼容处理的 Seedance 视频转为浏览器可播放的 H.264 MP4；MiniMax H3 返回 2K H.264 MP4。客户端应始终使用任务返回的 `video_url`。

## 6. 查询账号

```bash
curl https://pay.kokoai.online/openapi/v1/account \
  -H "Authorization: Bearer koko_live_xxxxxxxxx"
```

```json
{
  "user": {
    "id": "usr_xxx",
    "username": "customer",
    "balance": 185,
    "status": "active"
  },
  "balance": 185,
  "currency": "points"
}
```

## 7. 错误格式

```json
{
  "error": {
    "code": "INSUFFICIENT_POINTS",
    "message": "积分不足，本次需要 20 积分",
    "request_id": "req_xxx"
  }
}
```

| HTTP | code | 含义 |
| ---: | --- | --- |
| 400 | `INVALID_JSON` | 请求体不是有效 JSON |
| 400 | `MODEL_NOT_SUPPORTED` | 模型不受支持 |
| 400 | `INVALID_PROMPT` | 提示词为空或超过 6000 字符 |
| 400 | `INVALID_DURATION` | 时长不符合模型规格 |
| 400 | `INVALID_RATIO` | 比例不受支持 |
| 400 | `INVALID_RESOLUTION` | 清晰度不受支持 |
| 400 | `INVALID_MODE` | mode 不受支持 |
| 400 | `INVALID_COUNT` | count 不是 1 |
| 400 | `INVALID_IDEMPOTENCY_KEY` | 幂等键格式无效 |
| 400 | `INVALID_REFERENCE_IMAGES` | 参考图字段、数量或 URL 不符合要求 |
| 400 | `REFERENCE_UPLOAD_FAILED` | 参考图处理失败，积分已退回 |
| 400 | `CHARGE_REJECTED` | 当前账号价格或扣费规则不允许提交 |
| 401 | `INVALID_API_KEY` | API Key 无效或已停用 |
| 402 | `INSUFFICIENT_POINTS` | 积分不足 |
| 404 | `TASK_NOT_FOUND` | 任务不存在或不属于当前账号 |
| 404 | `NOT_FOUND` | API 路径不存在 |
| 429 | `RATE_LIMITED` | 单个 API Key 超过每分钟 120 次请求 |
| 502 | `UPSTREAM_ERROR` | 上游提交、查询或视频处理失败，失败任务自动退款 |
| 503 | `MODEL_MAINTENANCE` | 模型维护中，未扣积分 |
| 504 | `UPSTREAM_TIMEOUT` | 上游提交超时，积分已退回 |

## 8. 扣费和退款

1. 创建任务前检查积分。
2. 每个幂等键最多成功扣费一次。
3. 上游提交失败、参考图处理失败或任务最终失败时自动退款。
4. 维护模型和参数校验失败不会扣积分。
5. 只有任务成功完成才保留扣费。

## 9. 客户端建议

- 创建任务后保存 `id`，每 5-10 秒查询一次状态。
- 网络超时后使用相同 `Idempotency-Key` 重试。
- 只在 `completed` 时下载 `video_url`。
- 不要保存或直连上游临时文件地址。
- 不要把平台 API Key 当作上游厂商密钥使用。