# KOKO Seedance API

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

Base URL：

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

当前公开 API 提供 Seedance 2.0、Seedance 2.5 和 Seedance 2.5 不卡人脸满血版。图片、音频、文本和已下线模型不在此接口范围内。

## 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, 10, 15],
      "duration_prices": {"5": 15, "10": 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": [30],
      "duration_prices": {"30": 20},
      "reference_images": {"supported": true, "max": 30, "formats": ["jpeg", "png", "webp"]},
      "ratio": ["9:16", "1:1", "3:4", "4:3", "16:9"],
      "resolutions": ["720p"],
      "points": 20,
      "enabled": true,
      "maintenance": false
    },
    {
      "id": "seedance-2.5-special",
      "name": "Seedance 2.5 · 不卡人脸满血版",
      "description": "暂时维护，当前无法生成，请选择其他模型",
      "type": "video",
      "duration": 30,
      "durations": [30],
      "duration_prices": {"30": 65},
      "reference_images": {"supported": true, "max": 30, "formats": ["jpeg", "png", "webp"]},
      "ratio": ["9:16", "1:1", "3:4", "4:3", "16:9"],
      "resolutions": ["720p", "1080p"],
      "points": 65,
      "enabled": false,
      "maintenance": true
    }
  ]
}
```

`duration_prices` 和 `points` 的单位都是积分，并且已经应用当前账号的专属价格或所属代理站零售价。不要在客户端写死价格。

## 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`。

```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 | Seedance 2.5 不卡人脸版 |
| --- | --- | --- | --- |
| `duration` / `seconds` | `5`、`10`、`15` | `30` | `30` |
| `resolution` | `720p` | `720p` | `720p`、`1080p` |
| `ratio` / `aspect_ratio` | `9:16`、`1:1`、`3:4`、`4:3`、`16:9` | 同左 | 同左 |
| `mode` | `text-to-video`、`reference`、`first-frame` | 同左 | 同左 |
| `count` | 固定 `1` | 固定 `1` | 固定 `1` |
| 当前状态 | 可用 | 可用 | 维护中，提交返回 `503` |

`prompt` 必填，长度为 1-6000 个字符。特殊版也兼容模型别名 `seedance-2-5-special`。

### 幂等键和请求编号

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

### 参考图

Seedance 2.0 最多 9 张，Seedance 2.5 最多 30 张。三种字段只能选一种：

```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；客户端应始终使用任务返回的 `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 当作上游厂商密钥使用。