KOKO 视频生成 API

最后更新：2026-10-28。模型启停状态、账号实时积分价格和参考素材限制以 GET /models 返回为准。公开 API 只允许调用模型列表中当前启用并开放 OpenAPI 的模型；已删除/停用/退役的模型不能再调用（返回 MODEL_NOT_SUPPORTED）。

站点已上架（OpenAPI 暂未开放）：gyk-sd25-903（UUseedance2.5 903 满血稳定版 720P）已出现在主站/代理站，主站 50 积分、代理拿货 42 积分、代理站默认零售 50 积分；OpenAPI 暂不返回，30 秒上游稳定性仍在观察。

Base URL：

text

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

当前公开 API 提供以下模型（价格以 GET /models 实时返回为准）：

mm-h3-768-stable（minimaxh3 稳定版参数903）：15 / 30 秒 · 768p · 比例 16:9 / 9:16 / 1:1 · 最多 9 张参考图 + 3 个参考音频 · 20 / 40 积分/条
oo-sd25-1080p（OOseedance2.5 1080p超分 903参数）：固定 30 秒 · 1080p · 比例 16:9 / 9:16 / 1:1 / 3:4 · 最多 9 张参考图 + 3 个参考音频 · 40 积分/条
pp-sd25-stable（PPseedance2.5 稳定满血版）：固定 30 秒 · 720p / 1080p 可选 · 比例 16:9 / 9:16 / 1:1 / 3:4 · 最多 10 张参考图（不支持参考音频/参考视频）· 提示词不限长度 · 65 积分/条
minimax-h3-933（minimax-h3 1k 933）：固定 15 秒 · 1K · 最多 9 张参考图 · 20 积分/条
dp-sd20（seedance2.0 满血版）：5 / 15 秒 · 720p · 比例 16:9 / 9:16 / 1:1 · 最多 9 张参考图 · 25 积分/条

图片生成、音频生成、文本生成及已下线模型不在本接口范围内。已从模型列表删除/停用/退役的模型不能再调用。

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": "mm-h3-768-stable",
      "name": "minimaxh3 稳定版 参数903",
      "type": "video",
      "durations": [15, 30],
      "duration_prices": {"15": 20, "30": 40},
      "reference_images": {"supported": true, "max": 9, "formats": ["jpeg", "png", "webp"]},
      "reference_audios": {"supported": true, "max": 3},
      "ratio": ["16:9", "9:16", "1:1"],
      "resolutions": ["768p"],
      "points": 40,
      "max_prompt_length": 12000,
      "enabled": true,
      "maintenance": false
    },
    {
      "id": "oo-sd25-1080p",
      "name": "OOseedance2.5 1080p超分 903参数",
      "type": "video",
      "durations": [30],
      "duration_prices": {"30": 40},
      "reference_images": {"supported": true, "max": 9, "formats": ["jpeg", "png", "webp"]},
      "reference_audios": {"supported": true, "max": 3},
      "ratio": ["16:9", "9:16", "1:1"],
      "resolutions": ["1080p"],
      "points": 40,
      "max_prompt_length": 8000,
      "enabled": true,
      "maintenance": false
    },
    {
      "id": "pp-sd25-stable",
      "name": "PPseedance2.5 稳定满血版",
      "type": "video",
      "durations": [30],
      "duration_prices": {"30": 65},
      "reference_images": {"supported": true, "max": 10, "formats": ["jpeg", "png", "webp"]},
      "reference_audios": {"supported": false, "max": 0},
      "ratio": ["16:9", "9:16", "1:1"],
      "resolutions": ["720p", "1080p"],
      "points": 65,
      "max_prompt_length": 0,
      "enabled": true,
      "maintenance": false
    },
    {
      "id": "minimax-h3-933",
      "name": "minimax-h3 1k 933",
      "type": "video",
      "durations": [15],
      "duration_prices": {"15": 20},
      "reference_images": {"supported": true, "max": 9, "formats": ["jpeg", "png", "webp"]},
      "ratio": ["16:9", "9:16", "1:1", "4:3", "3:4"],
      "resolutions": ["1K"],
      "points": 20,
      "max_prompt_length": 10000,
      "enabled": true,
      "maintenance": false
    },
    {
      "id": "dp-sd20",
      "name": "seedance2.0 满血版",
      "type": "video",
      "durations": [5, 15],
      "duration_prices": {"5": 25, "15": 25},
      "reference_images": {"supported": true, "max": 9, "formats": ["jpeg", "png", "webp"]},
      "ratio": ["16:9", "9:16", "1:1"],
      "resolutions": ["720p"],
      "points": 25,
      "max_prompt_length": 8000,
      "enabled": true,
      "maintenance": false
    }
  ]
}

duration_prices、points 的单位都是积分；max_prompt_length: 0 表示不限制提示词长度。实际价格和可用状态以当前账号 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_20261028_001" \
  -d '{
    "model": "dp-sd20",
    "prompt": "一只小狗在草地上奔跑，镜头缓慢推进，阳光自然，画面稳定",
    "duration": 5,
    "ratio": "9:16",
    "resolution": "720p",
    "count": 1
  }'

PP2.5 示例（固定 30 秒，720p/1080p 可选）：

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: pp_order_20261028_001" \
  -d '{
    "model": "pp-sd25-stable",
    "prompt": "雨后的城市街道倒映霓虹，一辆复古汽车缓慢驶过，镜头平稳跟拍",
    "duration": 30,
    "ratio": "9:16",
    "resolution": "1080p",
    "image_urls": ["https://your-cdn.example.com/reference.png"]
  }'

参考音频示例（minimaxh3 稳定版，最多 9 图 + 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: mm_audio_20261028_001" \
  -d '{
    "model": "mm-h3-768-stable",
    "prompt": "根据参考图和参考音频生成自然连贯的视频，人物口型与音频同步",
    "duration": 15,
    "ratio": "16:9",
    "resolution": "768p",
    "image_urls": ["https://your-cdn.example.com/reference.png"],
    "audio_urls": ["https://your-cdn.example.com/reference.mp3"]
  }'

也可以分别使用 audio_urls / reference_audios；参考音频最多 3 个。当前模型不支持参考视频，参考素材数量以 GET /models 返回的能力为准。

json

{
  "id": "upstream_task_id",
  "status": "running",
  "model": "dp-sd20",
  "prompt": "一只小狗在草地上奔跑，镜头缓慢推进，阳光自然，画面稳定",
  "prompt_complete": true,
  "points": 25,
  "balance": 185,
  "video_url": null,
  "failure_reason": null,
  "created_at": "2026-09-17T12:00:00.000Z",
  "updated_at": "2026-09-17T12:00:00.000Z"
}

参数规则

模型	时长（秒）	分辨率	比例	参考图	参考音频	积分/条
`mm-h3-768-stable`	15 / 30	768p	16:9 / 9:16 / 1:1	最多 9 张	最多 3 个	20 / 40
`oo-sd25-1080p`	30	1080p	16:9 / 9:16 / 1:1 / 3:4	最多 9 张	最多 3 个	40
`pp-sd25-stable`	30	720p / 1080p	16:9 / 9:16 / 1:1 / 3:4	最多 10 张	不支持	65
`minimax-h3-933`	15	1K	16:9 / 9:16 / 1:1 / 4:3 / 3:4	最多 9 张	不支持	20
`dp-sd20`	5 / 15	720p	16:9 / 9:16 / 1:1	最多 9 张	不支持	25

prompt 必填。提示词上限：pp-sd25-stable 不限制（0），oo-sd25-1080p 8000，mm-h3-768-stable 12000，minimax-h3-933 10000，dp-sd20 8000；超过上限会在扣费前返回 400。

幂等键和请求编号

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

参考图

参考图上限：pp-sd25-stable 10 张，mm-h3-768-stable/oo-sd25-1080p/minimax-h3-933/dp-sd20 各 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。提示词里用 @图片1、@图片2 指代第 1/2 张参考图。Seedance 2.0/2.5 的人物参考必须这样绑定；只写“图片1=…”可能被模型当成普通文字，人物会变成随机脸。平台提交前会自动把“图片N / 图N / 参考图N”规范为 @图片N；超出本次实际上传数量的编号会按纯文本处理，不会因此报“缺少参考图”。

图片有两种给法，任选其一，也可以混用：

公网 HTTPS 链接（上面的写法）—— 需上游能直接访问到。
直接传图片内容（base64） —— 本地软件不必先上传到公网：

json

{"image_urls":["data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..."]}

json

{"image_urls":[{"base64":"iVBORw0KGgoAAAANSUhEUg...","mime":"image/png"}]}

图片限 JPG、PNG、WebP，单张不超过 50 MB；参考音频支持 MP3/WAV/M4A/AAC/FLAC（单个不超过 50 MB）；当前模型不支持参考视频。平台会把外部素材镜像/落盘成公网链接再提交，外部图片地址应保持可访问。任一图片下载或上传失败会终止提交并自动退回积分（400 INVALID_REFERENCE_MEDIA）。

参考音频说明

当前支持的参考音频模型：mm-h3-768-stable 最多 3 个，oo-sd25-1080p 最多 3 个；其它模型不支持参考音频或参考视频。
音频可以用公网 HTTPS URL，也可以直接传 base64（MP3/WAV/M4A/AAC/FLAC，单个不超过 50 MB）。
平台会把参考素材统一落盘成公网链接再提交；外部图片地址应保持可访问。
参考图与参考音频合计数量以对应模型 GET /models 返回的能力为准。

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-07（原文件下载改为直连上游 CDN）。适用于本平台公开视频 API，包括 Seedance 与 MiniMax H3；不是上游供应商的接口文档。

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

使用 API Key 查询 GET /openapi/v1/videos/{task_id}。
确认 status 为 completed 且 video_url 非空。
使用返回的完整 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 重新查询任务取得新地址。
原文件下载会先返回 307，Location 指向上游 CDN 直链（*.dola.com、*.douyinvod.com）；

浏览器与 HTTP 客户端直接连到该 CDN 取流，视频字节不经过本平台服务器。调用方不需要调用上游 signed_url，也不需要自行添加 passthrough=1；对非该渠道的任务，平台内部仍按原方式中继，调用方无感。

⚠️ 上游直链时效很短（约 30 秒）：必须在拿到 Location 后立即发起请求，不要缓存、排队或稍后再下。

失效后请对同一 /content 重新请求，平台会重新签发一条。

未带签名的 /videos/{task_id}/content 需要 API Key，正常先返回 307，Location 是短期签名地址（可能位于上游 CDN 域名）；这不是下载失败。HTTP 客户端应正确处理重定向。
⚠️ 不要把 API Key、Cookie 或任何本平台凭证发往跳转目标域名，不要使用 curl --location-trusted。

跳转目标确为第三方 CDN，携带凭证等于把你的 API Key 泄露给该域名。正确做法：只跟随跳转、不带 Authorization。需要浏览器播放时，可以使用签名地址作为媒体源，但跨域 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_MEDIA`	参考素材字段、数量、URL 或 base64 不符合要求
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. 扣费和退款

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

9. 客户端建议

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

10. New API / 第三方网关对接

New API（new-api）在「渠道」里填写 KOKO 的 Base URL 时，不要带最后的 /v1（new-api 会自己追加）：

text

Base URL: https://pay.kokoai.online/openapi

new-api 实际请求的是：

text

GET https://pay.kokoai.online/openapi/v1/models
Authorization: Bearer koko_live_xxxxxxxxx

如果网关要求填写完整的 OpenAPI 根地址，也可以直接填 https://pay.kokoai.online/openapi/v1。服务端同时兼容 .../openapi/v1/v1/models 和根路径 .../v1/models，上述两种 Base URL 都能获取模型列表。

使用 API CDN 时，把域名换成 https://api.kokoaii.top/openapi，路径规则相同。

返回的 data[].id 就是渠道里应填的模型名，例如 mm-h3-768-stable、oo-sd25-1080p、pp-sd25-stable、minimax-h3-933、dp-sd20。模型是否可用以当前 API Key 调用 GET /models 的实时返回为准。

下载有效期

成片下载地址有有效期，请尽快保存；具体时长以 GET /models 返回的 downloadTtlHours 为准。

过期后再请求 /content 会返回错误；请重新查询原任务或联系平台，不要为此重新创建收费生成任务。