文档 · 文生视频
免费的文生视频接口怎么用?三种状态,只有一种该放弃
auto/video 是异步的。提交一个提示词,拿回一个 id,然后轮询到任务结束。一条片子大约两分钟。真正要记住的一点:上游状态是 unknown 的任务仍然在跑——把它当失败处理,你的客户端会把马上要成功的活儿扔掉。
一句话定义
auto/video 是一种 tokenexchage 提供的文生视频能力别名:异步提交,拿回一个 id 再轮询到结束。一条片子约 2 分钟,建议每 15 秒轮询 1 次;背后有 9 个候选模型,任务状态只有 3 种(processing、succeeded、failed)。只收文生视频——图生视频要输入一张图,那是另一个操作、另一套请求形状。
关键数字
| 提交接口 | POST /v1/videos/generations |
| 查询接口 | GET /v1/videos/generations/{id} |
| 一条片子耗时 | 约两分钟 |
| 轮询间隔 | 10 到 15 秒 |
| 别名背后的候选模型数 | 9 |
三步接入
国际区账号请把 base_url 换成 https://alli.website/v1,请求形状与下面完全一致。用国际区 key 打 tokenexchage.com 会返回 401 invalid customer key。
- 向 https://tokenexchage.com/v1/videos/generations 发 POST,model 写 auto/video,prompt 写画面描述。
- 拿回响应里的 id,状态是 processing。
- 每 10 到 15 秒查一次 GET /v1/videos/generations/{id},直到 succeeded 取 url,或 failed 取 error。
提交
curl https://tokenexchage.com/v1/videos/generations \
-H "Authorization: Bearer sk-你的key" \
-H "Content-Type: application/json" \
-d '{"model":"auto/video","prompt":"云层翻过山脊,延时摄影"}'
{
"object": "video",
"id": "a1b2c3d4-…",
"status": "processing"
}
轮询
curl https://tokenexchage.com/v1/videos/generations/a1b2c3d4-… \
-H "Authorization: Bearer sk-你的key"
只有三种状态,没有别的:
status | 含义 | 怎么办 |
|---|---|---|
processing | 还在做 | 继续轮询 |
succeeded | 好了,url 有值 | 取地址 |
failed | 终态,error 说明原因 | 停下来报错 |
上游的 PENDING 和 RUNNING 都归到 processing,这没什么意外。要单独讲的是 UNKNOWN:任务刚提交、还没完全登记时上游会报这个状态,而它是瞬态的——我们自己的探测里,任务是先 UNKNOWN 后 SUCCEEDED,十一条全部出片。
所以 UNKNOWN 映射成 processing,不是 failed。如果映成失败,客户端在问得太早的那一刻就会放弃一个其实在跑的任务,而那些任务本来都会成功。
import time, requests
H = {"Authorization": "Bearer sk-你的key"}
base = "https://tokenexchage.com/v1/videos/generations"
job = requests.post(base, headers=H,
json={"model": "auto/video", "prompt": "云层翻过山脊"}).json()
while True:
st = requests.get(base + "/" + job["id"], headers=H).json()
if st["status"] == "succeeded": break
if st["status"] == "failed": raise SystemExit(st.get("error"))
time.sleep(10)
print(st["url"])
十到十五秒轮一次。一条片子约两分钟,一秒一次的循环基本只是在制造负载。
刻意没有的东西
只收文生视频。图生视频、参考图生视频、视频编辑都要输入一张图或一段片子,是另一个操作、另一套请求形状,不是这个接口上的一个开关。
别名只在当前模型被上游下线(404 / 410)时才会换候选。视频不是那种「换个模型重试一下」的请求:换个模型就是另一条片子,而你要看过才知道。
什么时候用文生视频
概念片、氛围镜头、短视频素材、分镜预演,是主要用法。共同点是片长短、要求「看起来对」多过「每一步都对」。需要精确表演、需要口型同步、需要严格符合分镜的,文生视频现在还给不了,那类需求要么实拍,要么用图生视频加参考图。
一条片子约两分钟,这个时间决定了它适合批量预生成、不适合即时交互。用户点一下就要看到结果的场景,要提前把片子备好,而不是当场等。
异步任务怎么管
提交拿到 id 之后,把它记在自己的任务表里,带上提交时间、提示词、状态。轮询不要写成「提交完就阻塞等两分钟」——进程重启、连接断开都会让那次等待白费,而任务本身还在跑。
轮询间隔 10 到 15 秒足够。一秒一次的循环不会让片子早出来,只是在制造无谓的请求。超过预期时长的任务要单独标出来,可能是上游卡住了,也可能只是排队长。
失败和重试
失败是终态,拿到 error 之后不要原地重试同一个 id——那个任务已经结束了。要重来就重新提交,并且把失败原因记下来:同样的提示词反复失败,说明是提示词本身的问题,不是运气。
片子拿到手之后尽快存到自己的存储里。返回的地址是临时的,而视频文件通常不小,等到要用的时候再取,可能已经过期了。
存储与成本
视频文件比图大得多,生成完要立刻转存到自己的对象存储。接口给的临时地址适合下载,不适合当长期资源引用——页面上挂着一个会过期的地址,用户过几天回来看就是坏图。
预生成的时候要算清楚容量。一条片子几秒到十几秒,但文件动辄几十兆;按每天生成多少条估一个月的量,再对比存储成本,比事后清理便宜得多。不再需要的中间产物定期删掉,只留成片。
异步任务的状态机
文生视频不是一次请求就拿到文件,而是一个状态机:提交 → 排队 → 渲染 → 成功或失败。每个状态都要有自己的超时和重试策略。
- 提交:只返回任务 id,不返回文件。记下 id 和提交时间。
- 轮询:每几秒查一次,连续多次无变化就退避,不要写死循环。
- 终态:成功给文件地址,失败给原因。失败先看是不是内容审核或时长超限。
成本控制
视频按秒计费,时长翻倍成本也翻倍。先出 5 秒草稿,确认构图和运动方向,再渲染 15 秒成片;分辨率同理,评审用低分辨率,定稿再出高清。
延伸阅读
- OpenAI API Reference —— 本页接口沿用的请求形状
- schema.org —— 本页结构化数据所用的类型定义
- Sitemap 协议 —— 站点页面的收录约定
常见问题
一条片子要等多久?
大约两分钟。轮询间隔建议 10 到 15 秒——一秒一次的循环基本只是在制造负载。
一共有几种状态?
只有三种:processing 继续轮询、succeeded 取地址、failed 终态报错。
上游的 UNKNOWN 是什么?
任务刚提交、还没完全登记时上游会报这个状态,它是瞬态的。平台把它映射成 processing 而不是 failed,否则客户端会在问得太早的那一刻放弃一个其实在跑的任务。
能图生视频吗?
只收文生视频。图生视频、参考图生视频、视频编辑都要输入一张图或一段片子,那是另一个操作、另一套请求形状。
其他能力
同一套命名,一个能力一个别名,都在 /v1/models 里: