# KOKO Seedance API

> 最后更新：2026-08-29。账号可用模型、实时积分价格和参考图限制以 `GET /models` 返回为准。

Base URL:

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

当前公开 API 只支持 Seedance 2.0 和 Seedance 2.5。图片、音频、文本和 MiniMax H3 不在此接口范围内。

## 1. API Key

客户登录 KOKO Studio 后，通过账号 API Key 管理入口创建 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 服务"}'
```

创建接口返回的 `secret` 只显示一次。客户也可以通过 `GET /api/account/api-keys` 查看自己已创建的 Key，通过 `DELETE /api/account/api-keys/{key_id}` 停用 Key。

请求时使用：

```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",
      "type": "video",
      "duration": 15,
      "durations": [5, 10, 15],
      "duration_prices": {"5": 15, "10": 20, "15": 25},
      "reference_images": {"supported": true, "max": 9, "formats": ["jpeg", "png", "webp"]},
      "ratio": ["9:16", "1:1", "3:4", "4:3", "16:9", "21:9"],
      "resolutions": ["720p"],
      "points": 25,
      "enabled": true
    },
    {
      "id": "seedance-2.5",
      "name": "Seedance 2.5",
      "type": "video",
      "duration": 30,
      "durations": [30],
      "duration_prices": {"30": 40},
      "reference_images": {"supported": true, "max": 30, "formats": ["jpeg", "png", "webp"]},
      "ratio": ["9:16", "1:1", "3:4", "4:3", "16:9", "21:9"],
      "resolutions": ["720p"],
      "points": 40,
      "enabled": true
    }
  ]
}
```

Seedance 2.0 支持 5、10、15 秒，分别扣 15、20、25 积分；Seedance 2.5 支持 30 秒，扣 40 积分。每个客户账号使用自己的余额和价格配置扣费。

## 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_20260828_001" \
  -d '{
    "model": "seedance-2.0",
    "prompt": "一只小狗在草地上跳舞，镜头缓慢推进，阳光自然，画面稳定",
    "duration": 5,
    "ratio": "9:16",
    "resolution": "720p",
    "reference_images": [
      {"url": "https://example.com/reference.png"}
    ]
  }'
```

`Idempotency-Key` 是强烈建议传入的业务订单号。相同客户使用相同订单号重试时不会重复扣积分。长度为 8-100，只允许字母、数字、下划线和横线。无法设置请求头的客户端可在 JSON 中传同规格的 `request_id`；两者都未提供时平台会自动生成，但客户端将无法依靠原订单号安全重试。

可选请求头 `X-Request-Id` 可用于链路排查，格式要求与 `Idempotency-Key` 相同；响应会回传同名请求头，错误响应中的 `request_id` 也与其一致。

创建成功会返回 `202` 或上游成功状态码：

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

### 参数规则

| 参数 | Seedance 2.0 | Seedance 2.5 |
| --- | ---: | ---: |
| `duration` | `5`、`10`、`15` 秒 | 固定 30 秒 |
| `resolution` | `720p` | `720p` |
| `ratio` | `9:16`、`1:1`、`3:4`、`4:3`、`16:9`、`21:9` | 同左 |
| 积分 | 15 / 20 / 25 | 40 |

### 参考图

Seedance 2.0 当前最多支持 9 张参考图片，Seedance 2.5 最多支持 30 张。推荐使用 `reference_images`：

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

也兼容 `image_urls` 或 `images` 数组，但三种字段不能同时传。每张图片必须是公网 HTTPS 地址，格式为 JPG、PNG 或 WebP，单张不超过 50 MB。服务端按数组顺序逐张下载并上传到 Seedance 上游，原始排序不会改变；任一张上传失败会终止本次提交并自动退回积分。参考图仅适用于图片输入，不支持把本地 `file://`、内网地址或 Base64 直接传给公开 API。

Seedance 2.5 如果触发肖像保护，请改用本人肖像或非人物参考图，或改用 Seedance 2.0 重试；失败任务会自动退回积分。

发生肖像保护、参考图不合规或上游拒绝时，具体可公开原因会写入任务的 `failure_reason`，不要只根据 HTTP 状态判断失败类型。

## 4. 查询任务

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

状态值：

- `queued`：已扣费，等待提交
- `running`：上游生成中
- `completed`：生成完成
- `failed`：生成失败，积分已自动退回

完成示例：

```json
{
  "id": "upstream_task_id",
  "status": "completed",
  "model": "seedance-2.5",
  "points": 40,
  "balance": 160,
  "video_url": "/openapi/v1/videos/upstream_task_id/content",
  "failure_reason": null,
  "created_at": "2026-08-28T12:00:00.000Z",
  "updated_at": "2026-08-28T12:03:18.000Z"
}
```

## 5. 获取视频文件

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

接口支持 HTTP Range，返回 `video/mp4`，适合直接交给播放器或下载器。正式站会把 Seedance 返回的非 H.264 视频转换为浏览器兼容的 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": 160,
    "status": "active"
  },
  "balance": 160,
  "currency": "points"
}
```

## 7. 错误格式

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

常见错误码：

| HTTP | code | 含义 |
| ---: | --- | --- |
| 401 | `INVALID_API_KEY` | API Key 无效或已停用 |
| 402 | `INSUFFICIENT_POINTS` | 积分不足 |
| 400 | `MODEL_NOT_SUPPORTED` | 不是 Seedance 2.0/2.5 |
| 400 | `INVALID_JSON` | 请求体不是有效 JSON |
| 400 | `INVALID_PROMPT` | 提示词为空或超过 6000 字符 |
| 400 | `INVALID_DURATION` | 时长不符合模型固定规格 |
| 400 | `INVALID_RATIO` | 比例不受支持 |
| 400 | `INVALID_RESOLUTION` | 清晰度不是 720p |
| 400 | `INVALID_IDEMPOTENCY_KEY` | 幂等键格式无效 |
| 400 | `INVALID_REFERENCE_IMAGES` | 参考图字段、数量或 URL 不符合要求 |
| 400 | `REFERENCE_UPLOAD_FAILED` | 参考图未能上传到上游，积分已退回 |
| 400 | `CHARGE_REJECTED` | 当前账号价格或扣费规则不允许提交 |
| 429 | `RATE_LIMITED` | 超过每分钟 120 次请求 |
| 404 | `TASK_NOT_FOUND` | 任务不存在或不属于当前客户 |
| 404 | `NOT_FOUND` | API 路径不存在 |
| 502 | `UPSTREAM_ERROR` | 上游提交或查询失败，失败任务会自动退款 |

## 8. 扣费规则

1. 创建任务前检查客户积分。
2. 上游提交前扣除一次积分。
3. 相同 `Idempotency-Key` 重试不重复扣费。
4. 上游提交失败、任务失败或上游密钥未配置时自动退款。
5. 只有任务成功完成才保留扣费。

## 9. 客户端建议

- 将 API Key 放在服务端环境变量，例如 `KOKO_API_KEY`。
- 创建任务后保存 `id`，每 5-10 秒查询一次状态。
- 只在 `completed` 时下载 `video_url`。
- 网络超时后使用相同 `Idempotency-Key` 重试，不要创建新的订单号。
- 不要把平台 API Key 当作上游 Seedance Key 使用。