
Seedance 2.5 Flash API 是 Seedance 2.5 API 中速度更快、成本更低的版本,在 PoYo 上只有一个模型 ID:seedance-2.5-flash。字节跳动于 2026 年 11 月 12 日发布了它;Seedance 2.5 Flash 模型页提供在线体验和实时价格。本指南带你从第一个 cURL 请求走到 Python 生产循环,使用的 schema 来自 Seedance 2.5 Flash API 文档,核对日期为 2026 年 11 月 16 日。
Seedance 2.5 Flash API 速览
| 项目 | 值 |
|---|---|
| 提交接口 | POST https://api.poyo.ai/api/generate/submit |
| 状态接口 | GET https://api.poyo.ai/api/generate/status/{task_id} |
| 鉴权请求头 | Authorization: Bearer $POYO_API_KEY |
| 模型 ID | seedance-2.5-flash(页面 slug seedance-2-5-flash 不是模型 ID) |
| 必填字段 | prompt、duration |
| 时长 | 整数秒,4–30 |
| 分辨率 | 480p 或 720p,默认 720p |
| 画面比例 | auto、21:9、16:9、4:3、1:1、3:4、9:16,默认 auto |
| 音频 | generate_audio,默认 true |
| 交付方式 | 异步任务:轮询状态或设置 callback_url |
用 cURL 发出第一个 Seedance 2.5 API 请求
把密钥导出为 POYO_API_KEY,并保存在服务端,不要放进浏览器代码。下面是一个 5 秒 480p 的文生视频请求,作为低成本的首次测试,费用为 92.5 积分:
curl --fail-with-body https://api.poyo.ai/api/generate/submit \
-H "Authorization: Bearer $POYO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.5-flash",
"input": {
"prompt": "A paper boat drifts under a stone bridge at sunrise. Slow tracking shot, gentle water sounds, no speech, no subtitles.",
"duration": 5,
"resolution": "480p",
"aspect_ratio": "16:9"
}
}'
提交成功会返回 code: 200 和一个 data 对象,其中包含 task_id、status(提交后立即为 not_started)和 created_time。这只是回执,不是视频。保存 task_id,然后查询:
curl --fail-with-body \
https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
-H "Authorization: Bearer $POYO_API_KEY"
状态依次为 not_started、running、finished 和 failed。任务为 finished 时,视频 URL 在 data.files[].file_url 中,file_type: "video";为 failed 时,读取 data.error_message。生成的文件保留 3 天,请复制到你自己的存储中。
Python:提交并在硬性截止时间内轮询
状态文档建议每 2–5 秒轮询一次,遇到 429 和 5xx 时退避,并且始终设置超时。下面的循环三点都做到了,而且超时后不会重新提交,因为第二次提交就是第二个计费任务。
import os
import time
import requests
BASE = "https://api.poyo.ai"
session = requests.Session()
session.headers["Authorization"] = "Bearer " + os.environ["POYO_API_KEY"]
def checked(response):
try:
body = response.json()
except ValueError:
response.raise_for_status()
raise
if body.get("code") != 200:
err = body.get("error") or {}
raise RuntimeError(
f"PoYo {body.get('code')} {err.get('type')}: "
f"{err.get('message') or body.get('detail')}"
)
return body["data"]
task = checked(session.post(BASE + "/api/generate/submit", json={
"model": "seedance-2.5-flash",
"input": {
"prompt": "A paper boat drifts under a stone bridge at sunrise. Slow tracking shot.",
"duration": 5,
"resolution": "480p",
"aspect_ratio": "16:9",
},
}, timeout=60))
task_id = task["task_id"]
print("Saved task:", task_id, flush=True)
deadline = time.monotonic() + 15 * 60
backoff = 5
while time.monotonic() < deadline:
r = session.get(f"{BASE}/api/generate/status/{task_id}", timeout=60)
if r.status_code == 429 or r.status_code >= 500:
time.sleep(backoff)
backoff = min(backoff * 2, 60)
continue
data = checked(r)
if data["status"] == "failed":
raise RuntimeError(data.get("error_message") or "Generation failed")
if data["status"] == "finished":
videos = [f["file_url"] for f in data.get("files", [])
if f.get("file_type") == "video"]
print(videos[0], "credits:", data.get("credits_amount"))
break
backoff = 5
time.sleep(5)
else:
raise TimeoutError("Still running; poll the saved task ID later: " + task_id)
作为参考,在 PoYo 于 2026 年 11 月 16 日的测试中,一段 4 秒 480p 的视频端到端约两分钟完成,一段 30 秒 720p 的视频不到三分钟。耗时随负载变化,所以 15 分钟的截止时间是安全上限,而不是预估值。
跳过轮询:使用 callback_url
在顶层、与 model 并列添加 callback_url。当任务变为 finished 或 failed 时,PoYo 会发送一个 POST,请求体就是任务数据对象(task_id、status、files、created_time、error_message),不带 code/data 包装。根据视频 webhook 文档:
- URL 必须是公网 HTTPS,最长 2048 个字符,不能是私有 IP。
- 在 30 秒内返回 2xx;投递失败会以指数退避最多重试 5 次。
- 按
base64(HMAC-SHA256(task_id + "." + timestamp, key))校验X-Webhook-Signature,其中timestamp取自X-Webhook-Timestamp,密钥通过GET /api/api-keys/webhook-secret获取。 - 让处理程序具备幂等性。如果所有重试都失败,状态接口中仍然有结果。
三种输入模式及 JSON 请求体
API 根据你发送的媒体选择模式,没有 mode 字段。
| 模式 | 触发条件 | 画面比例 |
|---|---|---|
| 参考生视频 | reference_image_urls、reference_video_urls、reference_audio_urls 中任一非空 | 任意支持的值 |
| 图生视频(首帧/尾帧) | image_urls 非空 | auto 或不传;输出跟随首帧 |
| 文生视频 | 无媒体 | 任意支持的值 |
image_urls 与参考字段要分开在不同请求中发送。以下请求体均为文档中的示例。
文生视频(30 秒 720p,提示词中带分时镜头列表):
{
"model": "seedance-2.5-flash",
"callback_url": "https://your-domain.com/callback",
"input": {
"prompt": "One continuous 30-second story of the same young woman in a yellow raincoat delivering a handwritten letter across a small seaside town at dawn. 0-6s: wide aerial shot of the sleepy harbor town, fishing boats rocking, soft morning light; she rides an old bicycle down a cobblestone hill. 6-12s: tracking shot beside her as she weaves past a fish market, seagulls lifting off, a vendor waves at her. 12-18s: low-angle shot as she climbs a steep stone staircase carrying the bicycle, breathing hard, the letter tucked in her pocket. 18-24s: she knocks on a blue door at the top; an elderly man opens it and she hands him the letter. 24-30s: close-up of the man reading, his eyes filling with tears; he smiles and says softly, \"She remembered.\" Camera slowly pulls back to reveal the sunrise over the sea. Natural ambient sound: waves, gulls, bicycle bell, footsteps, gentle piano music. No subtitles, no on-screen text.",
"duration": 30,
"resolution": "720p",
"aspect_ratio": "16:9",
"generate_audio": true
}
}
首帧和尾帧(一个 URL 固定开头,第二个固定结尾):
{
"model": "seedance-2.5-flash",
"input": {
"prompt": "Locked-off time-lapse of the red lakeside cabin: start from the summer evening in the first frame, let snow gradually cover the shore and the wooden dock as the sky darkens, and end exactly on the snowy night with the aurora in the last frame. Soft wind and crackling ice.",
"image_urls": [
"https://example.com/first-frame.jpg",
"https://example.com/last-frame.jpg"
],
"duration": 5,
"resolution": "720p",
"aspect_ratio": "auto"
}
}
参考生视频(按上传顺序以 @Image1、@Video1、@Audio1 引用文件):
{
"model": "seedance-2.5-flash",
"input": {
"prompt": "@Image1 is the ginger cat. It wears the yellow knitted scarf from @Image2 and is inside the bookstore from @Image3. On a rainy night the cat walks along a bookshelf, jumps down beside a reading lamp, and looks at the camera. Match the slow, cozy rhythm of @Audio1. No subtitles.",
"reference_image_urls": [
"https://example.com/cat.png",
"https://example.com/scarf.png",
"https://example.com/bookstore.png"
],
"reference_audio_urls": [
"https://example.com/rhythm.mp3"
],
"duration": 6,
"resolution": "480p",
"aspect_ratio": "16:9"
}
}
提交前要执行的校验规则
在客户端检查这些规则可以省去一次往返,也能给用户比通用 400 更清晰的提示。
| 字段 | 规则 |
|---|---|
prompt | 必填,非空字符串 |
duration | 必填整数,4–30 |
resolution | 仅限 480p 或 720p;1080p 需要 seedance-2.5 |
aspect_ratio | 七个值之一;使用 image_urls 时用 auto 或不传 |
image_urls | 1–2 个 URL(先首帧,后尾帧);JPEG、PNG 或 WebP,每个最大 30 MB;不能与参考字段同时使用 |
reference_image_urls | 最多 10 个;JPEG、PNG 或 WebP,每个最大 30 MB |
reference_video_urls | 最多 5 个;MP4 或 MOV,每个 2–30 秒、最大 200 MB;总时长最多 30 秒 |
reference_audio_urls | 最多 5 个;MP3 或 WAV,每个 2–30 秒、最大 15 MB;总时长最多 30 秒;需要同时有参考图像或视频 |
| 所有媒体 URL | 公网 HTTP 或 HTTPS,可直接下载(不能是登录页或会过期的预览链接) |
参考媒体的总时长在提交任务时检查。schema 还在 input 上设置了 additionalProperties: false,所以不要发送其他厂商 API 的字段,例如 seed 或 negative_prompt。
值得处理的错误
始终读取响应体中的 code 字段:提交接口的部分校验错误会以 HTTP 200 加 "code": 400 返回。错误码参考列出了以下错误:
| 代码 | 类型 | 处理方式 |
|---|---|---|
400 | validation_error、file_format_error、content_moderation_error | 修正请求或媒体;不要原样重试 |
401 | authentication_error | 检查 Bearer 请求头,并确认密钥仍然存在 |
402 | insufficient_credits_error | 充值后重新提交 |
429 | 速率限制 | 退避(1 秒、2 秒、4 秒……)后再轮询或提交 |
500、502、503 | 服务端或上游 | 以退避方式重试状态查询;重新提交前先检查状态 |
任务 failed | 设置了 error_message | 记录任务 ID;失败任务显示 credits_amount: 0 |
第一笔账单如何计算
不使用参考视频时,费用为输出秒数乘以每秒价格:480p 为 18.5 积分($0.0925),720p 为 41 积分($0.205),1 积分 = $0.005。生成音频不额外收费。
| 上文请求 | 计费秒数 | 积分 | 美元 |
|---|---|---|---|
| cURL 测试,5 秒 480p | 5 | 92.5 | $0.4625 |
| 文生视频,30 秒 720p | 30 | 1,230 | $6.15 |
| 首帧/尾帧,5 秒 720p | 5 | 205 | $1.025 |
| 参考图像 + 音频,6 秒 480p | 6 | 111 | $0.555 |
只要添加任何 reference_video_urls,就会切换到较低的含视频价格(480p 为 11.5 积分,720p 为 25.5 积分),按计费秒数计算:输出时长加上每个参考视频向下取整到整秒的时长。Seedance 2.5 API 价格明细逐一计算了这些情况。已完成任务的费用显示在状态响应的 credits_amount 中。
需要 1080p 时切换到 Seedance 2.5
请求字段相同,所以把任务从 Flash 迁到标准版 Seedance 2.5 模型,只需改模型 ID:
{
"model": "seedance-2.5",
"input": {
"prompt": "A paper boat drifts under a stone bridge at sunrise. Slow tracking shot.",
"duration": 5,
"resolution": "1080p",
"aspect_ratio": "16:9"
}
}
有两点细节:seedance-2.5 文档把 resolution 列为必填,所以始终要发送;标准模型最多允许 30 张图像、10 个视频和 10 个音频参考。1080p 下每秒 114 积分($0.57)。路由决策见 Seedance 2.5 Flash vs Seedance 2.5;Seedance 2.5 与其他厂商的对比见 Kling 4.0 vs Seedance 2.5。
常见问题
Seedance 2.5 Flash API 的模型 ID 是什么? seedance-2.5-flash,使用点号。带连字符的 seedance-2-5-flash 只是模型页的 slug。
Seedance 2.5 Flash API 支持 1080p 吗? 不支持。它接受 480p 和 720p。要原生 1080p,请发送同样的请求体,并设置 "model": "seedance-2.5" 和 "resolution": "1080p"。
如何在 Seedance 2.5 API 中关闭音频? 设置 "generate_audio": false 得到无声视频,或者保留音频,在提示词中去掉个别音轨,例如“no background music”(无背景音乐)。
能在一个 Seedance 2.5 Flash 请求中同时使用首帧和参考图像吗? 不能。image_urls 和 reference_* 字段必须分开在不同请求中发送。
一个 Seedance 2.5 Flash API 任务需要多长时间? 在 PoYo 2026 年 11 月 16 日的测试中,4 秒 480p 端到端约两分钟,30 秒 720p 不到三分钟。请使用轮询或回调,而不是让请求一直保持打开。
Seedance 2.5 Flash 任务失败会扣费吗? 不会。失败任务不收费,其状态显示 credits_amount: 0。