第 2 课
查询任务状态、阅读成功与失败返回,并取得成片地址
查询任务状态、阅读成功与失败返回,并取得成片地址
课程目录第 2 / 3 课
学习位置仅保存在当前浏览器,有效期 180 天。
查询任务状态、阅读成功与失败返回,并取得成片地址
本课对照官方文档「查询视频生成任务」「创建视频生成任务」「Doubao Seedance 2.5 系列教程」编写。命令在 2026-11-21 核对;成功返回采用官方查询文档里的示例 JSON,以及创建文档里的轮询打印。本环境未用真实密钥跑出成功视频。
本课目标
- 用官方查询接口按任务 ID 读取状态,并按官方示例做轮询
- 看懂
queued、running、succeeded、failed等状态 - 从成功返回里取出
content.video_url,并记住 URL 与任务 ID 的有效期 - 对照官方
usage字段,把计费用量对到completion_tokens - 看懂失败时的
error.code、error.message,尤其是首帧任务用错ratio时的异步报错
前置条件
- 已完成第 1 课,本机已安装
arkruntime,并已导出ARK_API_KEY - 手里最好有一个刚创建的任务 ID。若还没有,可以用第 1 课的官方文生视频示例再提交一次
- 成功成片的字段结构以官方文档示例为准;你自己跑出来的 ID、URL 和 token 数会不同
第 1 步:先记住这是异步查询
官方「创建视频生成任务」写明:创建是异步接口,获取 ID 后需要通过查询视频生成任务 API 来查询任务状态。任务成功后会输出生成视频的 video_url。
查询接口是:
GET https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks/{id}
对应 SDK 方法是 client.content_generation.tasks.get。官方查询文档还给出这些保存规则,跟做成片时要立刻转存,不要只把链接记在聊天记录里:
- 其他视频任务 ID(非 Draft)有效期均为 7 天,从
created_at起算,超时后自动失效 - 视频 URL 有效期为 24 小时,请及时下载或转存
- Seedance 2.5 系列模型生成的视频 URL 下载次数上限为 100 次
第 2 步:用官方 curl 查询一次
把 $TASK_ID 换成第 1 课拿到的任务 ID。下面就是官方「查询视频生成任务」页的 curl 示例,未改路径和请求头:
TASK_ID="your_task_id"
curl -X GET \
"https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks/$TASK_ID" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ARK_API_KEY"
完整接口地址单独占一行:
https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks/$TASK_ID

2026-11-21 实拍。右侧「输出示例」里的
model是官方原文的doubao-seedance-2-0-260128,status为succeeded。Flash 调用成功时,model字段会不同。https://ark.volcengine.com/region:cn-beijing/docs/get-video-generation-task-api
如果任务还在排队或生成中,你可能先看到 queued 或 running,需要稍后再查。官方文生视频示例的做法是:只要还不是 succeeded 或 failed,就等待 10 秒再查询。
用假 Key 查询时,接口会在读到任务之前先拒绝鉴权。2026-11-21 00:04(Australia/Perth,与 Asia/Shanghai 同时区)用假 Key ark-test-invalid-key-kun-course 查询一个不存在的 ID cgt-test-invalid,HTTP 状态码为 401,响应正文与第 1 课假 Key 创建任务相同,code 为 AuthenticationError,message 为 The API key format is incorrect.。这说明查询接口同样要求合法密钥。
第 3 步:对照官方成功返回,取出成片地址
官方「查询视频生成任务」页用下面这段 JSON 说明成功时的字段结构。请注意:示例里的 model 是 doubao-seedance-2-0-260128,这是官方文档示例,不是 Flash。你用 doubao-seedance-2-5-flash-261115 调用时,model 字段会不同;status、content.video_url 和 usage 的结构应与官方一致。本课不编造 Flash 的成功输出。
{
"id": "cgt-2026****-****",
"model": "doubao-seedance-2-0-260128",
"status": "succeeded",
"content": {
"video_url": "https://ark-content-generation-cn-beijing.tos-cn-beijing.volces.com/xxx"
},
"usage": {
"completion_tokens": 108900,
"total_tokens": 108900
},
"created_at": 1779348818,
"updated_at": 1779348874,
"seed": 78674,
"resolution": "720p",
"ratio": "16:9",
"duration": 5,
"framespersecond": 24,
"service_tier": "default",
"execution_expires_after": 172800,
"generate_audio": true,
"draft": false,
"priority": 0
}
读成功结果时,先确认 status 为 succeeded,再打开 content.video_url。官方还写明:usage.total_tokens 等于 usage.completion_tokens,因为视频生成模型不统计输入 token,输入 token 为 0。计费对账请看 usage.completion_tokens。官方定价页也强调:准确 token 用量以该字段为准。
查询文档列出的任务状态有:
queued:任务排队中running:任务运行中cancelled:任务已取消。取消状态 24h 自动删除(只支持queued状态的任务被取消)succeeded:任务成功failed:任务失败expired:任务超时
官方创建文档里,Python 示例在轮询成功后打印的对象长这样。这段同样来自官方文档,其中 model 是旗舰 ID doubao-seedance-2-5-260628,video_url 被写成占位符 https://xxx。Flash 调用成功时,你应看到相同的字段名,但 model 会不同:
----- polling task status -----
Current status: running, Retrying after 10 seconds...
Current status: running, Retrying after 10 seconds...
Current status: running, Retrying after 10 seconds...
...
----- task succeeded -----
ContentGenerationTask(id='cgt-20260414114820-*****', model='doubao-seedance-2-5-260628', status='succeeded', error=None, content=Content(video_url='https://xxx', last_frame_url=None, file_url=None), usage=Usage(completion_tokens=411300, total_tokens=411300), frames=None, framespersecond=24, created_at=1776138520, updated_at=1776139219, seed=33608, service_tier='default', execution_expires_after=172800, generate_audio=True, duration=11, ratio='16:9', output_format='mov', resolution='720p', draft=False, draft_task_id=None)
成片地址出现后,请在 24 小时内下载或转到自己的存储。官方建议配置火山引擎 TOS 的数据订阅,把推理产物自动转存到自己的桶中。
成功成片采用官方文档示例,本环境未用真实密钥跑出成功视频。
第 4 步:单独写一段轮询脚本
第 1 课的官方文生视频示例已经包含轮询。若你只拿着一个已有的任务 ID,想反复查询,可以用官方查询页同一套 SDK 写法,只保留 tasks.get 这一段:
import os
import time
from arkruntime import Ark
client = Ark(
base_url="https://ark.cn-beijing.volces.com/api/v3",
api_key=os.environ.get("ARK_API_KEY"),
)
task_id = "your_task_id" # 换成第 1 课返回的 id
while True:
get_result = client.content_generation.tasks.get(task_id=task_id)
status = get_result.status
if status == "succeeded":
print("----- task succeeded -----")
print(get_result)
print("video_url:", get_result.content.video_url)
print("completion_tokens:", get_result.usage.completion_tokens)
break
elif status == "failed":
print("----- task failed -----")
print(f"Error: {get_result.error}")
break
else:
print(f"Current status: {status}, Retrying after 10 seconds...")
time.sleep(10)
其中创建客户端、tasks.get、以及按 succeeded / failed 分支处理的方式,都来自官方文生视频示例;打印 video_url 和 completion_tokens 是为了让你对照上一节官方 JSON 里的同名字段。不要在任务仍是 queued 或 running 时去取视频地址。
第 5 步:阅读失败返回,不要忽略异步报错
官方查询文档写明:任务成功时 error 返回 null,任务失败时返回错误数据,内含 error.code 和 error.message。官方文档没有给出一条固定的失败 JSON 示例,本课不编造失败输出。你在本地看到失败时,先把这两个字段完整记下。
更需要注意的是报错时机。官方系列教程「报错机制」把校验分成两种:
- 同步报错:提交任务时接口立即返回错误。例如全模态参考任务里,显式把
omni_reference_task_type设为edit或extend,但参数不符合该类型限制时,会在创建时就失败。 - 异步报错:任务已经创建,要等到启动后再失败,查询时
status才会变成failed。首帧 / 首尾帧生视频如果参数不符合特殊限制,就属于这一类。
因参数配置和任务类型不兼容导致的异步报错,官方给出的错误码是 InvalidParameter.TaskTypeConstraint。下一课做首帧生成时,ratio 必须为 adaptive;如果写成 16:9 这类固定比例,任务可能先创建成功,再在查询时报这个错误。官方还提醒:Seedance 2.5 系列在特定任务类型中,需排队等待到任务被消费时,才会返回报错信息。不要因为创建接口返回了 ID,就以为参数一定合法。
常见坑
- 只看创建接口的返回,不再查询。创建成功只表示任务已受理,成片在查询结果的
content.video_url里。 - 把官方示例 JSON 里的
doubao-seedance-2-0-260128或轮询打印里的doubao-seedance-2-5-260628当成 Flash 的成功输出。那是官方示例用的其他型号,Flash 的model字段会不同。 - 过了 24 小时才去打开视频 URL,或短时间里下载超过 100 次。
- 把
queued、running当成失败。按官方示例等待并重试即可。 - 忽略异步报错。首帧任务用错
ratio时,错误往往出现在查询阶段,而不是创建阶段。
小结
到这里,你已经能按官方查询接口轮询任务,从成功返回里取出成片地址和 completion_tokens,也知道失败时该读 error。成功成片采用官方文档示例,本环境未用真实密钥跑出成功视频。下一课会按官方限制做首帧生成,分清 Flash 与旗舰的差异,并对照刊例估算费用。

