KovAPIKovAPI
seedance-2.5-flash

Seedance 2.5 Flash · API

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

Seedance 2.5 Flash 视频生成接口(字节跳动),Seedance 2.5 的 Flash 版,按秒计费,单价低于 Seedance 2.5。异步任务:提交后立即返回任务号,再查询或用 Webhook 拿到 MP4。支持 4–30 秒、480P / 720P、5 种画面比例;参考图(最多 10 张)、参考视频(最多 5 段)和参考音频(最多 5 段)可以放在同一个请求里,成片自带声音。失败不收费。

在 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-flash", "prompt": "雨夜的霓虹街道,一只纸船顺着积水漂过,镜头低角度跟随,水花和倒影清晰", "duration": 5, "resolution": "720P", "size": "16:9"}'

返回(HTTP 202)

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

第 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-flash",
  "data": [
    {"url": "https://img.kovapi.com/i/8c1f0e5d2b7a49e3a6d0c4f1b9e2a7d5.mp4"}
  ],
  "usage": {"clips": 1, "model": "seedance-2.5-flash"}
}

第 3 步 · data[0].url 就是成片(MP4),保留 7 天;需要长期使用,请下载到你自己的存储。

完整示例(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-flash",
    "prompt": "雨夜的霓虹街道,一只纸船顺着积水漂过,镜头低角度跟随,水花和倒影清晰",
    "duration": 5,
    "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-flash.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 秒
分辨率480P / 720P
画面比例16:9 / 9:16 / 1:1 / 4:3 / 3:4
参考图最多 10 张 · 用作参考(人物、场景、风格),不作首帧
参考视频最多 5 段,合计不超过 30 秒
参考音频最多 5 段,每段不超过 30 秒
声音固定带声音(对白、音效和配乐由模型生成),不能关
提示词长度最多 11,000 个字符(中英文一样计)
计费方式按秒:每秒单价 × 下单的秒数

请求参数

POST /v1/videos/generations 的请求体(JSON):

参数类型必填说明
modelstring是模型 id:seedance-2.5-flash。
promptstring是画面、镜头和动作的描述,最多 11,000 个字符(中英文一样计)。
durationinteger否时长(秒),4–30 之间的整数,不传为 4。也可以写作 seconds。
resolutionstring否分辨率:480P / 720P,不传为 720P。请带上 P(720 这样不带 P 的写法会被拒绝)。
sizestring否画面比例:16:9 / 9:16 / 1:1 / 4:3 / 3:4,不传为 16:9。也可以写作 aspect_ratio。
imagesarray否参考图,最多 10 张,用来定人物、场景和风格,不会被当成首帧。在提示词里按传入顺序用 @Image1、@Image2 点名。只有一张时也可以放在 image。
video_referencesarray否参考视频,最多 5 段,合计不超过 30 秒。可以和参考图一起传(照片定人物外貌,视频定动作和运镜),在提示词里用 @Video1 点名。每段可以是公网链接,也可以是 data:video/mp4;base64,...(mp4 / mov,单段不超过 50MB,整个请求不超过 100MB)。链接要能直接下载到文件本身;YouTube、B 站、抖音、网盘分享页这类网页链接不行,提交时会直接返回 400。
audio_referencearray否参考音频,最多 5 段,每段不超过 30 秒(按实际时长算,30.1 秒也会被拒),用公网 http(s) 链接,要和参考图或参考视频一起传,在提示词里用 @Audio1 点名。链接要能直接下载到文件本身;YouTube、B 站、抖音、网盘分享页这类网页链接不行,提交时会直接返回 400。
audioboolean否成片固定带声音(对白、音效和配乐由模型按提示词生成),不能关闭;传 false 不起作用。
callback_urlstring否任务结束时把结果推送到这个地址,见下文的 Webhook。
ninteger否每个任务出 1 条视频,不用传。传了大于 1 的值也只出 1 条,但提交时会按 n 条预扣,任务结束后退回多扣的部分。

其他字段(如 seed、negative_prompt、fps、watermark)不会转发,也不影响价格;成片一律是 MP4,通过 url 返回。

价格

按秒计费:费用 = 所选分辨率的每秒单价 × 下单的秒数。提交时按这个金额预扣,成功按同样的金额结算,失败全额退回。1 积分 = $0.005。

分辨率积分 / 秒美元 / 秒5 秒一条
480P12$0.06$0.30
720P24$0.12$0.60

带参考视频的单按下表计价:计费秒数 = 参考视频秒数 + 输出秒数,参考音频不计费。

分辨率积分 / 秒美元 / 秒5 秒输出 + 5 秒参考视频
480P7$0.035$0.35
720P14$0.07$0.70

参考素材

  • 参考图最多 10 张,用来定人物、场景、产品和风格。Seedance 不把图片当首帧:想让某张图里的人物或物品出现在画面里,就在提示词里点名它(@Image1、@Image2 …,按传入顺序编号)。
  • 参考视频最多 5 段(合计 30 秒以内),用来定动作、运镜和节奏;参考音频最多 5 段(每段不超过 30 秒,30.1 秒也会被拒),用来定说话的声音或配乐,要和参考图或参考视频一起传。三种素材可以放在同一个请求里,分别用 @Image1 / @Video1 / @Audio1 点名。
  • 支持真人人脸参考图,无需遮挡。请确保你有权使用图中人物的肖像。
  • 每张参考图的宽和高都要在 300–6000 像素之间,宽高比在 0.4–2.5 之间(195×195 的小图或 1:3 的长条图都不行)。不符合的在提交时就返回 400 reference_image_dimensions,写明是第几张、实际尺寸多少,不计费。
  • 每张图可以是公网图片链接、data: URI 或 base64,单张不超过 16MB,多张用数组放在 images 里。提交时我们先把图片转存好再排队;读不到的图片会直接返回 400,message 写明是第几张,这一单不计费。
  • 我们转存的参考素材和成片都保留 7 天。

参考图 + 参考视频一起用

curl
curl https://kovapi.com/v1/videos/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "seedance-2.5-flash", "prompt": "@Image1 的女孩在 @Image2 的街道上,跳 @Video1 里的舞", "images": ["https://example.com/character.png", "https://example.com/street.png"], "video_references": ["https://example.com/dance.mp4"], "duration": 5, "size": "16:9"}'

@Image1 是第 1 张参考图,@Video1 是第 1 段参考视频。带参考视频时,参考视频的秒数也计费,单价见价格表。

内容要求

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

什么时候审

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

不收费

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

声音

成片的声音(对白、旁白、歌声和音效)由模型按提示词生成,和画面一起审核:提示词里写的台词、旁白和歌词会被念出来或唱出来。不需要人声的片子,提示词里就别写台词和歌词。这个型号每条成片都带声音,不能关闭;请求里传 audio: false 不起作用。上传的参考音频同样要过审,受版权保护的音乐作参考音频可能被拒。声音没通过时,error.param 为 audio,message 会写明是生成的声音还是上传的参考音频。

常被拒的内容

  • 色情、裸露或性暗示,包括 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 天,视频链接保留 7 天。

出片时间

720P 一般 4–8 分钟,480P 一般 2–3 分钟;时长越长越久,高峰排队时会更久。

错误与退款

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

提交时返回的错误

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

任务失败(status 为 failed)

code什么时候出现怎么办
content_policy视频:提示词、参考素材,或生成的画面 / 声音没通过内容审核(声音被拦时 param 为 audio)。 Wan 标准版和 Prime:输入素材未通过审核。error.reason 为 FaceDetectionSuspect(疑似真人面部)或 DataInspectionFailed(输入内容审核未通过)。error.message 说明原因和调整建议;失败任务未计费。改写提示词或更换素材后再提交;原样重交还会被拒。
request_rejected视频:上游没有接受这次请求,并说明了原因;message 里附上游原话(例如某个参考素材无法处理)。按原话修改提示词或参考素材后再提交;原样重交通常还会失败。不计费。
render_failed视频:这次没有生成出成片,多为偶发。原样重新提交通常就能成功。
invalid_material视频:上游认为输入素材有问题。这是一个笼统的报错,也常是偶发。先原样重交;反复出现再检查参考素材和提示词长度。
duration_rejected视频:时长没有被接受。最常见的是参考音频或参考视频超过上限,哪怕只超零点几秒。把参考音频 / 视频剪到上限以内再提交;原样重交还会失败。
reference_unreadable视频:模型下载不到参考图、视频或音频,常见是 YouTube、网盘分享页这类网页链接。换成能直接下载到文件的链接,或者在 Playground 本地上传;原样重交还会失败。
render_timeout视频:排队或渲染时间过长,上游放弃了这一单。重新提交。
wait_timeout视频:超过 120 分钟仍未生成结果,按超时处理,积分全额退还;之后如果生成成功,视频免费交付。重新提交。
upstream_unstable视频:渲染过程中连接中断。重新提交。
result_fetch_failed视频已经生成,但我们反复下载或保存成片都没有成功。重新提交。
upstream_error其他失败:自动重试后仍然失败、排队 15 分钟还没开始、上游拒绝但没有说明原因等,message 写明具体情况。通常重新提交就能成功。

请按 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-flash", "prompt": "雨夜的霓虹街道,一只纸船顺着积水漂过,镜头低角度跟随,水花和倒影清晰", "duration": 5, "resolution": "720P", "size": "16:9", "callback_url": "https://your-domain.com/webhook"}'