第 2 课

查询任务状态、阅读成功与失败返回,并取得成片地址

查询任务状态、阅读成功与失败返回,并取得成片地址

图文22 分钟

课程目录第 2 / 3 课

学习位置仅保存在当前浏览器,有效期 180 天。

01 / 图文教材

查询任务状态、阅读成功与失败返回,并取得成片地址

本课对照官方文档「查询视频生成任务」「创建视频生成任务」「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

官方「查询视频生成任务」页:GET 路径、有效期说明与成功返回示例

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 与旗舰的差异,并对照刊例估算费用。