文档 · 文生视频

免费的文生视频接口怎么用?三种状态,只有一种该放弃

作者:tokenexchage 团队 · 最后更新:2026-10-17

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。

  1. 向 https://tokenexchage.com/v1/videos/generations 发 POST,model 写 auto/video,prompt 写画面描述。
  2. 拿回响应里的 id,状态是 processing。
  3. 每 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——那个任务已经结束了。要重来就重新提交,并且把失败原因记下来:同样的提示词反复失败,说明是提示词本身的问题,不是运气。

片子拿到手之后尽快存到自己的存储里。返回的地址是临时的,而视频文件通常不小,等到要用的时候再取,可能已经过期了。

存储与成本

视频文件比图大得多,生成完要立刻转存到自己的对象存储。接口给的临时地址适合下载,不适合当长期资源引用——页面上挂着一个会过期的地址,用户过几天回来看就是坏图。

预生成的时候要算清楚容量。一条片子几秒到十几秒,但文件动辄几十兆;按每天生成多少条估一个月的量,再对比存储成本,比事后清理便宜得多。不再需要的中间产物定期删掉,只留成片。

异步任务的状态机

文生视频不是一次请求就拿到文件,而是一个状态机:提交 → 排队 → 渲染 → 成功或失败。每个状态都要有自己的超时和重试策略。

成本控制

视频按秒计费,时长翻倍成本也翻倍。先出 5 秒草稿,确认构图和运动方向,再渲染 15 秒成片;分辨率同理,评审用低分辨率,定稿再出高清。

延伸阅读

常见问题

一条片子要等多久?

大约两分钟。轮询间隔建议 10 到 15 秒——一秒一次的循环基本只是在制造负载。

一共有几种状态?

只有三种:processing 继续轮询、succeeded 取地址、failed 终态报错。

上游的 UNKNOWN 是什么?

任务刚提交、还没完全登记时上游会报这个状态,它是瞬态的。平台把它映射成 processing 而不是 failed,否则客户端会在问得太早的那一刻放弃一个其实在跑的任务。

能图生视频吗?

只收文生视频。图生视频、参考图生视频、视频编辑都要输入一张图或一段片子,那是另一个操作、另一套请求形状。

其他能力

同一套命名,一个能力一个别名,都在 /v1/models 里:

image

auto/image

文生图。同步,几秒不是几分钟

embedding

auto/embed

1024 维向量,单候选

rerank

auto/rerank

按相关度重排检索结果

tts

auto/tts

文字转语音

asr

auto/asr

语音转文字