Seedance 视频生成 API 中转:异步任务、轮询和那些不看文档想不到的坑
2026 年上半年视频模型迭代得很猛,四模态输入、原生音画同步、镜头延长这些能力陆续进了 API。但真正把视频接进生产流程的团队,卡住的地方往往很朴素:任务提交成功了,然后不知道该多久去查一次;查到 finished,下载链接已经过期;或者客户端等不及超时重试,一次创意生成扣了两次钱。
先接受一个前提:视频不是请求-响应
文本模型是同步或流式,一次 HTTP 连接里把结果拿回来。视频生成是长耗时任务,标准形态是:
① POST 提交任务 → 返回 task_id
② 轮询 GET 状态 → pending / running / succeeded / failed
③ 成功后取结果 URL
④ 转存到自己的存储
这意味着你的系统里要多个东西:任务表、状态机、重试与幂等、超时上限、结果落盘、失败告警。只写一个 requests.post 然后 .json() 的,一定会在第一次长任务上翻车。
一个最小可跑的骨架:
import os, time, requests
BASE = os.environ["RELAY_BASE_URL"].rstrip("/")
KEY = os.environ["RELAY_API_KEY"]
H = {"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"}
# 提交
r = requests.post(
f"{BASE}/v1/video/generations",
headers=H,
json={
"model": "doubao-seedance-2-0-fast-260128",
"prompt": "特写,雨后的柏油路面反射霓虹,镜头缓慢前推",
"duration": 5,
"resolution": "480p",
},
timeout=30,
)
r.raise_for_status()
task_id = r.json()["id"]
# 轮询:指数退避 + 总超时,别每秒打一次
deadline = time.time() + 900
delay = 3
while time.time() < deadline:
s = requests.get(f"{BASE}/v1/video/tasks/{task_id}", headers=H, timeout=15).json()
if s["status"] in ("succeeded", "failed"):
break
time.sleep(delay)
delay = min(delay * 1.5, 20)
else:
raise TimeoutError(f"task {task_id} 超时,保留 ID 供人工核查")
端点和字段名各家聚合平台不一样,上面是形态示意。接之前一定先看文档里的任务提交地址、状态枚举和结果字段,别照抄。
三个最容易出事的地方
一、提交超时 ≠ 任务失败。 网络抖动导致 POST 没收到响应,任务可能已经在下游排队了。这时候盲目重试,就是两个任务两份钱。稳妥做法是提交时带一个业务侧幂等键(如果平台支持),或者超时后先按业务单号查一次任务列表,确认没创建成功再重试。
二、轮询别太密。 视频生成几十秒到几分钟,每秒查一次会把状态接口的配额吃光,还容易被限流。指数退避起步 3 秒、上限 20 秒比较合适,同时设一个总超时(比如 15 分钟)。超时后不要删任务,把 task_id 留住,人工核查或者异步补查,因为下游很可能还在跑。
三、结果 URL 是临时的。 拿到 succeeded 之后第一件事是把文件转存到自己的对象存储,别把平台返回的链接直接写进业务数据库。我见过上线一周后整批素材 403 的,重跑一遍的钱比当初多得多。
计费口径也要重新算
视频通常按次、按时长、按分辨率档位计,不是按 token。sd-2-5-480p 这种 ID 里的 480p 就是档位信息,换到 720p / 1080p 是另一档价格。
提前确认四件事:失败任务是否计费、同一任务轮询是否计费、超时但下游已生成的怎么结、参考素材(首帧图、音频、参考视频)上传是否单独算。批量生产里这四项能把预算拉偏很多。
还有一点:视频任务的失败原因常常在任务详情里,不在提交响应里。轮询拿到 failed 后要把 error 字段完整落日志,别只记一句「生成失败」,否则下周复盘时完全不知道是内容策略、参数还是上游波动。
素材上传的体积问题
四模态输入意味着可能同时传图、传参考视频、传音频。base64 编码膨胀约三分之一,几十 MB 的请求体很容易撞上网关的 client_max_body_size 或上传超时。能传 URL 就传 URL;必须传文件时,先确认平台有没有提供独立的上传端点。
doubao-seedance-2-0-fast-260128 这个 ID 带日期后缀,手打极易错。我从 /v1/models 返回里复制,并且在部署脚本里加了一次 ID 存在性校验 —— 视频任务一次成本不低,因为拼错一个字符白跑一轮不划算。
和文本模型放在同一个入口的好处
这条流水线我是在 token173.net 上跑的:先用文本模型把分镜描述扩写、再交给 doubao-seedance-2-0-fast-260128 生成、最后用轻量模型批量写标题和标签。三段共用一个 Key、一套鉴权和一份账单,不用为视频单独开账号、单独对账。控制台里文本、gpt-image-2 那类图像型号和视频型号归在一起,切换时只改 model 字符串,这点对做多模态工作流的人比单价更实在。
需要说明,长耗时任务的通道稳定性比峰值速度重要。国内直连省掉了自己折腾跨境链路的麻烦,但超时、重试、幂等这些还是得业务侧自己做,平台不会替你兜。
上线前的检查清单
- 任务表有
task_id、业务单号、状态、提交时间、耗时、扣费、错误详情 - 提交带幂等键,或超时后先查再重试
- 轮询指数退避 + 总超时,超时保留 ID
- 结果自动转存自有存储,不依赖临时 URL
- 失败原因完整落日志
- 视频任务单独的 Key 和额度上限,避免失控烧钱
- 用固定 20 条分镜跑通全流程,再放量
- 模型 ID 从
/v1/models拉取并校验
视频能力接进来,工作量一大半在任务编排上,模型调用反而只占几行。把状态机和幂等先写扎实,后面换任何型号、换任何平台,这套骨架都能复用。