seedance-2.5-30s

Seedance 2.5 · Special · API

POST https://kovapi.com/v1/videos/generations

4–30秒任选，720P，16:9或9:16。最多30张参考图、10段参考音频，不支持参考视频。无参考音频$2/条（400积分）；传参考音频$3/条（600积分），时长不影响单价。原生生成音轨不算参考音频。短期开放，不承诺长期供应。生成时间随排队变化，请查询原任务，不要重复提交；失败全额退。

在 Playground 试用 →

快速开始

三步跑通：提交任务 → 查询结果 → 拿到视频链接。把 YOUR_API_KEY 换成你的 Key，下面的命令可以直接运行。

第 1 步 · 提交任务（立刻返回任务号，HTTP 202）

curl

curl https://kovapi.com/v1/videos/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "seedance-2.5-30s", "prompt": "一位旅行者走过秋天的山谷小镇，从清晨走到黄昏，镜头一路跟拍", "duration": 25, "resolution": "720P", "size": "16:9"}'

返回（HTTP 202）

JSON

{
  "id": "img_5c2e8f1a9b3d7e6f0a4c8b2d",
  "object": "video.generation.job",
  "status": "queued",
  "created": 1791281400,
  "model": "seedance-2.5-30s"
}

第 2 步 · 每 5–10 秒查询一次，直到 status 变成 succeeded 或 failed

curl

curl https://kovapi.com/v1/videos/jobs/img_5c2e8f1a9b3d7e6f0a4c8b2d \
  -H "Authorization: Bearer YOUR_API_KEY"

成功时的返回

JSON

{
  "id": "img_5c2e8f1a9b3d7e6f0a4c8b2d",
  "object": "video.generation.job",
  "status": "succeeded",
  "created": 1791281400,
  "model": "seedance-2.5-30s",
  "data": [
    {"url": "https://img.kovapi.com/i/8c1f0e5d2b7a49e3a6d0c4f1b9e2a7d5.mp4"}
  ],
  "usage": {"clips": 1, "model": "seedance-2.5-30s"}
}

第 3 步 · data[0].url 就是成片（MP4），保留 15 天；需要长期使用，请下载到你自己的存储。

完整示例（Python：提交 → 等待 → 保存到本地）

Python

import time
import requests

BASE = "https://kovapi.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

# 1. 提交任务
job = requests.post(f"{BASE}/videos/generations", headers=HEADERS, json={
    "model": "seedance-2.5-30s",
    "prompt": "一位旅行者走过秋天的山谷小镇，从清晨走到黄昏，镜头一路跟拍",
    "duration": 25,
    "resolution": "720P",
    "size": "16:9",
}).json()
if "error" in job:
    raise SystemExit(job["error"]["message"])

# 2. 每 10 秒查询一次，最多等一小时
deadline = time.time() + 3600
while job["status"] not in ("succeeded", "failed") and time.time() < deadline:
    time.sleep(10)
    job = requests.get(f"{BASE}/videos/jobs/{job['id']}", headers=HEADERS).json()

# 3. 下载视频
if job["status"] == "succeeded":
    url = job["data"][0]["url"]
    with open("seedance-2.5-30s.mp4", "wb") as f:
        f.write(requests.get(url).content)
    print("saved", url)
elif job["status"] == "failed":
    print("failed:", job["error"]["code"], job["error"]["message"])
else:
    print("still", job["status"], job["id"])

排队时，查询结果里还有 queue_position（前面还有几个任务）和 eta_seconds（预计还要等几秒）。超过你设的等待时间也不要重新提交：任务还在，稍后用同一个任务号接着查。

认证

Header

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

在控制台创建 API Key 后即可调用。

规格速览

时长	4–30 秒
分辨率	720P
画面比例	16:9 / 9:16
参考图	最多 30 张 · 用作参考（人物、场景、风格），不作首帧
参考视频	不支持
参考音频	最多 10 段
声音	固定带声音，不能关（传 `audio: false` 会被拒绝）
计费方式	按条：一条一个价，和时长无关

请求参数

参数	类型	必填	说明
model	string	是	模型 ID，此处为 seedance-2.5-30s。
prompt	string	是	描述内容、镜头和动作。
duration	integer	否	时长秒数，4–30 的任意整数（默认 30，即最长的那个——按条计费，时长不影响价格）。也可写作 seconds。
resolution	string	否	720P
size	string	否	画幅：16:9 / 9:16（默认 16:9）。也可写作 aspect_ratio。本模型不支持 21:9。
image	string	否	图生视频：带参考图即走图生视频，可传公网 URL、data: URI 或 base64；不带则为文生视频。
images	array	否	多张参考图，最多 30 张。超过上限直接报错，不会截断。也可写作 reference_images。
audio_reference	string / array	否	公网HTTPS链接或链接数组，最多10段；必须搭配至少1张参考图。上传MP3/WAV/M4A，每段最多15MB、30秒。只要传入参考音频，本条费用为$3（600积分）。
audio	boolean	否	成片固定带声音，不能关闭；传 `false` 会被拒绝（400），可以不传。
callback_url	string	否	任务结束时把结果推送到这个地址，见下文的 Webhook。
n	integer	否	每个任务出 1 条视频，不用传。传了大于 1 的值也只出 1 条，但提交时会按 n 条预扣，任务结束后退回多扣的部分。

价格

短期开放 · 按条计费

	积分 / 条	美元 / 条
无参考音频	400	$2.00
传参考音频	600	$3.00

参考素材

参考图最多 30 张，用来定人物、场景和风格，不会被当成首帧；在提示词里用 @Image1、@Image2 点名。

支持真人人脸参考图，无需遮挡。请确保你有权使用图中人物的肖像。

JSON · $3

{
  "model": "seedance-2.5-30s",
  "prompt": "Follow @Image1 and use @Audio1 as the soundtrack",
  "duration": 25, "resolution": "720P", "size": "16:9",
  "images": ["https://example.com/reference.png"],
  "audio_reference": ["https://example.com/reference.mp3"]
}

内容要求

Seedance 的每个任务都要经过内容审核，范围包括提示词、参考素材和生成的成片，画面和声音都审。没通过审核的任务以 content_policy 失败，不收费。

什么时候审

提交时先审提示词和参考素材，成片生成后再审一次画面和声音。所以被拒的结果可能在提交后几秒内返回，也可能要等到渲染结束，半小时以上才返回。任务以 status 为 failed、error.code 为 content_policy 结束，就是没通过审核；用 Webhook 会收到 video.failed 事件。

不收费

被拒的任务不扣费：提交时预扣的金额在任务结束时全额退回，调用日志里也显示未计费。

声音

成片的声音（对白、旁白、歌声和音效）由模型按提示词生成，和画面一起审核：提示词里写的台词、旁白和歌词会被念出来或唱出来。不需要人声的片子，提示词里就别写台词和歌词。这个型号每条成片都带声音，不能关闭。上传的参考音频同样要过审，受版权保护的音乐作参考音频可能被拒。

常被拒的内容

色情、裸露或性暗示，包括 AI 生成或合成的画面
血腥、残忍、自残，以及中枪、流血等暴力伤害
枪支、爆炸物、毒品
涉及未成年人的性化内容一律不行；未成年人和烟酒、毒品或危险行为同框也会被拒
政治人物、明星、体育和商界名人等公众人物的形象或声音，包括长得很像的人物
受版权保护的角色和 IP 形象，例如迪士尼、漫威角色
仇恨、歧视内容和虚假新闻

长分镜脚本

一条成片只要有一个镜头违规，整条都会被拒，长分镜脚本最容易踩到：动作戏里的枪战和流血特写、未成年人出现在饮酒或吸烟的场景里，都会让整条失败。提交前通读一遍，删掉或改写这类镜头。

真人肖像

用真人照片作参考，需要你有权使用其肖像；各型号能否用真人参考图，见本页上方的说明。

被拒之后

原样重新提交还会被拒。先找出可能违规的那部分，改写提示词或更换参考素材，再重新提交。

错误码: content_policy · status: failed

upstream_line_unavailable: 生成服务过载或可用资源不足时，返回 upstream_line_unavailable。本次失败不计费，预扣积分退还，请稍后重试。该错误没有指出具体的参数或素材问题。明确的时长限制、素材读取失败和审核拒绝仍分别返回 duration_rejected、reference_unreadable 和 content_policy；请按对应提示调整。

任务状态与返回字段

GET /v1/videos/jobs/{id} 返回这些状态，各字段的说明见异步任务。每 5–10 秒查一次，或者用下面的 Webhook 等推送。查询不收费，同一个账号的任何 Key 都能查。

状态	含义
queued	排队中。返回里带 `queue_position`（前面还有几个任务）和 `eta_seconds`（预计等待秒数）。
processing	生成中。
succeeded	已完成。结果在 `data[0].url`，计费明细在 `usage`。
failed	失败。原因在 `error`，预扣的积分已全额退回。

processing 有时会回到 queued：例如服务繁忙、成片正在重新取回，或者服务重启。任务没能完成时，网关可能自动重新生成；无论重试几次，一个任务只扣一次费用。
同一个账号最多 50 个任务同时生成，更多的任务按提交顺序排队；排队超过 15 分钟还没开始的任务会自动失败并全额退款。任务记录保留 3 天，视频链接保留 15 天。

出片时间

错误与退款

提交时出错会直接返回 HTTP 4xx / 5xx，不建任务、不扣费；提交成功后的失败写在查询结果里，预扣的积分全额退回。全部错误码见错误码。

提交时返回的错误

HTTP	code	原因	怎么办
400	invalid_request	参数不合法：时长、分辨率、比例或素材数量超出这个模型的范围，提示词太长，参考图或参考视频读不到，或者给固定带声音的模型传了 `audio: false` 等。`message` 写明原因。	按 `message` 修改后重新提交。
400	invalid_callback_url	`callback_url` 不是公网的 http(s) 地址，或超过 2000 个字符。	换成能从公网访问的地址。
400	model_not_found	型号写错、没有传 `model`，或这个型号不能用在这个接口上（例如拿对话模型调生图接口）。	以 `GET /v1/models` 或 API 手册里的模型 id 为准。
401	invalid_api_key	Key 不存在、已删除或已停用，或者账号已停用。	到控制台「API Keys」页面检查这把 Key。
402	insufficient_quota	余额不够预扣这一单。网关先按这一单可能的最高费用预扣，同时发很多请求时也可能出现。	如果是并发突发，稍等几秒重试；否则充值。
429	rate_limit_exceeded	超过了这把 Key 设置的每分钟请求数（按最近 60 秒计）。不带 `Retry-After`。	等几秒再试，或在控制台调高这把 Key 的上限。
503	model_maintenance	型号维护中，暂停接单，期间不会改由其他模型作答。	维护结束后重试，进度见服务状态。
503	service_unavailable	我们这边临时出错，例如保存参考素材失败。这一单没有创建任务，也没有扣费。	稍后重试。

任务失败（`status` 为 `failed`）

code	什么时候出现	怎么办
content_policy	视频：提示词、参考素材，或生成的画面 / 声音没通过内容审核（声音被拦时 `param` 为 `audio`）。 Wan 标准版和 Prime：输入素材未通过审核。`error.reason` 为 `FaceDetectionSuspect`（疑似真人面部）或 `DataInspectionFailed`（输入内容审核未通过）。`error.message` 说明原因和调整建议；失败任务未计费。	改写提示词或更换素材后再提交；原样重交还会被拒。
duration_rejected	视频：时长没有被接受。最常见的是参考音频或参考视频超过上限，哪怕只超零点几秒。	把参考音频 / 视频剪到上限以内再提交；原样重交还会失败。
reference_unreadable	视频：模型下载不到参考图、视频或音频，常见是 YouTube、网盘分享页这类网页链接。	换成能直接下载到文件的链接，或者在 Playground 本地上传；原样重交还会失败。
invalid_video_request	提交时没有接受这次的参数或参考素材，没有开始生成。	检查时长、画幅和参考素材后再提交。本次不计费。
special_failed	生成失败，没有出片。	本次不计费，可以原样重新提交。
special_unknown	没有收到这次提交是否成功的明确答复。为避免重复生成，没有再次提交。	本次不计费，可以重新提交。
special_fetch	成片已经生成，但多次取回都失败了。	本次不计费，请重新提交。
special_unavailable	特价版暂时不可用，或任务等了 120 分钟仍没有开始生成。	本次不计费，请稍后再提交。

请按 code 判断，不要匹配 message 的文字。遇到不认识的 code（或者没有 code），按 upstream_error 处理：重新提交通常就能成功。失败的任务一律全额退款。

用 Webhook 代替轮询

提交时加上 callback_url，任务一结束（成功或失败），网关就把和查询接口完全一样的结果推送到这个地址，带签名，失败会自动重试。也可以在控制台「设置 → Webhook」里配一个账户级地址。 Webhook 文档 →

curl · callback_url

curl https://kovapi.com/v1/videos/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "seedance-2.5-30s", "prompt": "一位旅行者走过秋天的山谷小镇，从清晨走到黄昏，镜头一路跟拍", "duration": 25, "resolution": "720P", "size": "16:9", "callback_url": "https://your-domain.com/webhook"}'