# KOKO 视频生成 API

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

Base URL：

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

当前公开 API 提供 `seedance-2.0`、`seedance-2.5`、`seedance-2.5-workflow`（seedance2.5 不卡脸80%过）和 `minimaxh3`。图片生成、音频生成、文本生成和已下线模型不在此接口范围内。

## 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": 9, "10": 12, "15": 15},
      "reference_images": {"supported": true, "max": 30, "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": 15},
      "reference_images": {"supported": true, "max": 30, "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-workflow",
      "name": "seedance2.5 不卡脸80%过",
      "description": "固定30秒，人像参考图可自动旋转180度，自动添加声明",
      "type": "video",
      "max_prompt_length": 14809,
      "duration": 30,
      "durations": [30],
      "duration_prices": {"30": 15},
      "reference_images": {"supported": true, "max": 30, "formats": ["jpeg", "png", "webp"]},
      "ratio": ["9:16", "1:1", "3:4", "4:3", "16:9"],
      "resolutions": ["720p"],
      "points": 15,
      "enabled": true,
      "maintenance": false
    },
    {
      "id": "minimaxh3",
      "name": "minimaxh3 2K 933满血",
      "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` 的单位都是积分。所有模型的实际价格以当前账号 `GET /models` 的实时返回为准，不应硬编码示例价格。工作流返回独立 ID `seedance-2.5-workflow`，时长固定 30 秒、分辨率 720p，计费沿用该账号 Seedance 2.5 API 价格。

## 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 秒。价格以当前账号的模型列表为准。

MiniMax H3 参考视频和参考音频示例：

```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_av_20260926_001" \
  -d '{
    "model": "minimaxh3",
    "prompt": "参考视频中的动作和镜头节奏，并跟随参考音频生成自然连贯的视频",
    "duration": 15,
    "ratio": "16:9",
    "resolution": "2K",
    "attachments": [
      {
        "type": "video",
        "url": "https://example.com/reference.mp4",
        "mime": "video/mp4",
        "duration_seconds": 10
      },
      {
        "type": "audio",
        "url": "https://example.com/reference.mp3",
        "mime": "audio/mpeg"
      }
    ]
  }'
```

也可以分别使用 `video_urls` / `reference_videos` 和 `audio_urls` / `reference_audios`。参考视频最多 3 个，每个视频必须提供 `duration_seconds`，多条参考视频总时长不超过 15 秒；参考音频最多 3 个；MiniMax H3 的图片、视频、音频混合参考素材合计最多 10 个。

```json
{
  "id": "upstream_task_id",
  "status": "running",
  "model": "seedance-2.0",
  "prompt": "一只小狗在草地上奔跑，镜头缓慢推进，阳光自然，画面稳定",
  "prompt_complete": true,
  "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`、`10`、`15` | 固定 `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` |
| 参考视频 | 不支持 | 不支持 | 最多 3 个，总时长不超过 15 秒 |
| 参考音频 | 支持 | 支持 | 最多 3 个 |
| 当前状态 | 可用 | 可用 | 可用 |

`prompt` 必填。Seedance 2.0/2.5 最多 15000 个字符，MiniMax H3 最多 7000 个字符。工作流自动声明与提示词合计最多 15000 个字符，可填写长度由 `GET /models` 的 `max_prompt_length` 返回。字符长度按 JavaScript UTF-16 单元计算。工作流其余参数沿用表中的 Seedance 2.5。

### 不卡脸 2.5 工作流

```json
{
  "model": "seedance-2.5-workflow",
  "prompt": "参考图片中的构图，镜头缓慢推进，画面稳定",
  "duration": 30,
  "resolution": "720p",
  "ratio": "16:9",
  "mode": "reference",
  "reference_images": [
    {"url": "https://example.com/portrait.png", "portrait": true},
    {"url": "https://example.com/scene.png"}
  ]
}
```

仅标记 `portrait: true`（或 `category: "portrait"`）的图片在提交时旋转 180°；未标记的图片、音频及其他模型的素材不旋转。不要预先旋转又标记人像，以免重复旋转。声明由服务端自动添加，无需客户填写。名称中的“80%”不是成功率承诺，审核及生成结果以上游实际返回为准。重试沿用原始素材及人像标记，不叠加旋转。

### 幂等键和请求编号

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

### 参考图

Seedance 2.0、Seedance 2.5 每次最多支持 30 张参考图；MiniMax H3 最多支持 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。任一图片下载或上传失败会终止提交并自动退回积分。

### MiniMax H3 参考视频和音频

- 推荐使用 `attachments` 传混合参考素材，每项通过 `type` 标明 `image`、`video` 或 `audio`。
- 也兼容 `video_urls`、`reference_videos`、`audio_urls` 和 `reference_audios`。
- 所有素材必须是上游可直接访问的公网 HTTPS URL。
- 参考视频必须提供正确的 `duration_seconds`；缺失、为 0 或多条合计超过 15 秒会在提交前拒绝，不扣费或自动退款。
- MiniMax H3 最多 9 张参考图、3 个参考视频、3 个参考音频，混合素材合计最多 10 个。

## 4. 查询任务

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

状态：

- `submitting`：已接收，正在处理参考素材或向上游提交，不代表生成排队。
- `queued`：兼容历史任务状态；上游自身的排队无法由本站取消。
- `running`：上游生成中。
- `completed`：生成完成，可以读取 `video_url`。
- `failed`：生成失败，积分已自动退回，原因在 `failure_reason`。

上游明确返回余额不足、审核拒绝等错误时，任务结束并按失败规则退款，不会伪装成无限排队。网络超时等结果不确定的情况仍使用同一幂等键恢复，避免重复生成。

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

创建任务、幂等重试及查询任务的成功响应均返回 `prompt` 和 `prompt_complete`。`prompt` 是本账号提交并被服务接受的完整提示词（沿用提交时去除首尾空白的规则，保留内部换行和中文），不追加上游内部指令。运行中、成功、失败任务查询均支持；已归档的历史提示词会从归档读取。若历史归档缺失、损坏或校验失败，返回 `prompt: null, prompt_complete: false`，不会将截断摘要冒充完整提示词。此变更不修改计费或生成参数。

## 5. 提取视频地址与下载原文件

> 下载协议更新：2026-10-04。适用于本平台公开视频 API，包括 Seedance 与 MiniMax H3；不是上游供应商的接口文档。

### 5.1 推荐方式：查询任务，提取 video_url，再下载

1. 使用 API Key 查询 `GET /openapi/v1/videos/{task_id}`。
2. 确认 `status` 为 `completed` 且 `video_url` 非空。
3. 使用返回的完整 `video_url` 发起普通 GET，保存二进制响应。

以下是 Bash 示例，需安装 `curl` 和 `jq`；`KOKO_API_KEY` 请通过服务端环境变量配置。示例不会创建新任务或产生生成费用。

```bash
BASE="https://pay.kokoai.online/openapi/v1"
TASK_ID="替换为已有任务ID"
: "${KOKO_API_KEY:?请先配置 KOKO_API_KEY}"

task_json="$(curl --fail --silent --show-error \
  --connect-timeout 15 --max-time 60 \
  -H "Authorization: Bearer ${KOKO_API_KEY}" \
  "${BASE}/videos/${TASK_ID}")" || exit 1

VIDEO_URL="$(printf '%s' "$task_json" | jq -er \
  'select(.status == "completed") | .video_url | select(type == "string" and length > 0)')" \
  || { printf '任务未完成或尚未返回下载地址\n' >&2; exit 1; }

# 签名下载地址本身已经授权，不再发送 API Key、Cookie 或 Referer。
# 先写临时文件，仅在完整传输成功后改名，避免将中断文件当作成品。
curl --fail --location --show-error \
  --proto '=https' --proto-redir '=https' --max-redirs 5 \
  --connect-timeout 15 --max-time 600 \
  --output "koko-video.mp4.part" "$VIDEO_URL" \
  && mv -- "koko-video.mp4.part" "koko-video.mp4"
```

下载超时值是客户端示例配置，不是服务端速度或完成时间保证。`completed` 表示生成成功，不代表所有来源文件在任何网络下都能立即下载；下载失败请重新查询原任务，不要重新创建收费生成任务。

### 5.2 下载鉴权、域名与有效期

- 查询任务：需要 `Authorization: Bearer <你的 API Key>`。
- `video_url`：带短期签名的下载地址，有效期为生成该地址后约1小时；无需额外 Authorization、Cookie 或 Referer。请像临时访问凭证一样保护它。
- 原样保留整个 URL，不能删除签名参数、替换域名、截断查询串或修改 `media_intent`。过期返回401时，用 API Key 重新查询任务取得新地址。
- 当前新返回的下载地址使用查询请求所在站点域名；主站请求通常返回 `pay.kokoai.online`。服务器内部读取已验证原文件或中继上游/CDN，客户端不需要调用上游 `signed_url`，也不需要自行添加 `passthrough=1`。
- 未带签名的 `/videos/{task_id}/content` 需要 API Key，正常先返回 **307**，`Location` 是短期签名地址；这不是下载失败。HTTP 客户端应正确处理重定向。
- 不要把 API Key 转发给外部媒体/CDN域名，不要使用 `curl --location-trusted`。需要浏览器播放时，可以使用签名地址作为媒体源，但跨域 JavaScript 读取还取决于该响应的 CORS；下载附件与网页预览并非同一接口契约。
- 下载目标是原始视频文件，不保证统一转码为 H.264；网页预览可能采用不同版本。不要用网页预览文件大小或哈希校验原文件。

### 5.3 另一入口：Bearer content

```bash
# GET：自动跟随307取得签名地址并下载原文件
curl --fail --location --show-error \
  --proto '=https' --proto-redir '=https' --max-redirs 5 \
  --connect-timeout 15 --max-time 600 \
  -H "Authorization: Bearer ${KOKO_API_KEY}" \
  --output "koko-video.mp4.part" \
  "${BASE}/videos/${TASK_ID}/content" \
  && mv -- "koko-video.mp4.part" "koko-video.mp4"
```

也可以关闭客户端的自动跳转，读取307响应的 `Location`，再用**不带 Authorization**的新请求下载签名地址。不要把307响应体保存成MP4。

### 5.4 HEAD、Range 与断点续传

```bash
# 查看长度、类型、ETag等；HEAD没有视频响应体
curl --fail --head --location --show-error "$VIDEO_URL"

# 只取前1024字节，用于连通性探测，不是完整视频
curl --fail --location --show-error \
  -H "Range: bytes=0-1023" \
  --output "koko-video-prefix.bin" "$VIDEO_URL"
```

- 完整GET通常返回 `200`；单段Range被接受时返回 `206`，检查 `Content-Range` 和本段实际字节数。
- 示例 `bytes=0-1023` 正常应为1024字节。不能把它保存为“完整视频”后判定视频损坏。
- 无效或越界范围可能返回 `416`。若请求Range却返回200，应按完整文件处理，不能直接追加到旧文件。
- 断点续传应保存同一文件的强ETag或Last-Modified，配合 `If-Range`；仅在响应范围、校验标识一致时追加。标识不可用、已改变或服务端返回完整200时，重新完整下载，避免拼接不同文件版本。
- 完整传输结束后，若有 `Content-Length`，实际字节数必须一致；必要时用播放器或 `ffmpeg` 验证完整可解码。响应可能使用 `video/mp4`、`application/octet-stream` 或 `binary/octet-stream`，不能只依赖扩展名判断。

### 5.5 错误排查

| 现象/状态 | 处理 |
| --- | --- |
| `307` | 读取Location继续请求，或开启自动跳转。 |
| `401` | 无签名入口检查API Key；签名地址检查过期/参数是否完整，重新查询任务。 |
| `404` | 检查任务ID以及是否属于当前API Key账号。来源文件不可用时也可能收到相应错误。 |
| `409 VIDEO_NOT_READY` | 任务尚未完成，继续查询原任务。 |
| `416` | Range越界或格式不支持，先HEAD核对长度。 |
| `429` | 降低请求频率，按响应提示退避重试。 |
| `502 / 503 / 504`、连接超时 | 记录时间、任务ID和请求ID，重新查询并有限次数重试；不要重新提交生成或认为已自动退款。 |
| 返回JSON/HTML而非视频 | 读取错误内容，不要把错误响应保存成MP4。 |
| 下载中断/长度不足 | 保留为临时文件，核验同一版本后续传或重新下载，不要宣布成功。 |

定位问题时提供：任务ID、发生时间及时区、客户端出口IP、HTTP状态码、响应的 `X-Request-Id`（如有），以及DNS/连接/首字节/总耗时。不要公开 API Key、Cookie、完整签名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` | 提示词为空或超过该模型 `max_prompt_length` |
| 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 当作上游厂商密钥使用。