查询视频任务

创建任务后使用创建响应里的 id 查询进度和结果；创建方法见创建视频任务。

查询状态：GET /v1/video/generations/{task_id}

下载成片：GET /v1/videos/{task_id}/content

查询接口在任务完成后会在 metadata.url 返回视频地址。平台优先返回上游原始视频地址；只有上游没有可用地址时，才回退到带 access 能力的平台制品地址。上游原始地址可能带签名和过期时间，可以直接在浏览器或播放器中打开；平台制品地址同样可用。也可以携带 API Key 调用 /v1/videos/{task_id}/content 下载视频文件。

请求参数 · path

参数	类型	必填	说明
`task_id`	string	是	创建响应中的 `id`

请求示例

curl "$LOCOPAL_API_ORIGIN/v1/video/generations/$LOCOPAL_TASK_ID" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY"

下载视频

任务状态变为 completed 后，直接使用查询响应中的 metadata.url：

curl -L "$LOCOPAL_API_ORIGIN/v1/videos/$LOCOPAL_TASK_ID/content" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -o "$LOCOPAL_TASK_ID.mp4"

响应参数

参数	类型	说明
`id`	string	公开任务 ID
`task_id`	string	与 `id` 相同的兼容字段
`object`	string	固定为 `video`
`model`	string	视频模型 ID
`status`	string	`queued`、`in_progress`、`completed`、`failed` 或 `unknown`
`progress`	integer	当前进度，范围 0 至 100
`created_at`	integer	创建时间（Unix 秒）
`completed_at`	integer	完成时间，未完成时不返回
`metadata.url`	string	视频地址，成功时返回；优先为上游原始地址，必要时为平台制品地址
`metadata.upstream_created`	boolean	是否已在上游创建任务
`duration_secs`	integer	视频时长（秒），上游返回时提供
`expires_at`	integer	上游 URL 过期时间（Unix 秒），仅上游明确返回时提供
`framespersecond`	integer	视频帧率，上游返回时提供
`generate_audio`	boolean	是否生成同步声音，上游返回时提供
`ratio`	string	输出比例，上游返回时提供
`resolution`	string	输出分辨率，上游返回时提供
`seed`	integer	随机种子，上游返回时提供
`output_format`	string	输出格式，例如 `mp4`，上游返回时提供
`execution_expires_after`	integer	任务结果保留时长，上游返回时提供
`usage`	object	任务结算后的实际用量与费用；任务未结算（排队中、生成中或创建刚受理）时不返回
`usage.prompt_tokens`	integer	本次计费的视频 token 数（与账单「Tokens」列左侧数字一致）
`usage.completion_tokens`	integer	视频/图片任务不单独上报输出 token，固定为 `0`
`usage.total_tokens`	integer	总用量，等于 `usage.prompt_tokens`
`usage.quota`	integer	本次任务实际消耗的积分
`usage.amount`	number	本次任务金额（元），由 `usage.quota` 按平台结算口径换算，保留 6 位小数；控制台账单对同一笔费用按 4 位小数展示
`usage.currency`	string	金额币种，固定为 `CNY`
`error.code`	string	失败错误码，仅失败时返回。平台视频任务终态失败通常为 `video_generation_failed`；无法归一化的上游错误可能保留上游错误码
`error.message`	string	失败原因，仅失败时返回。平台会先剥离多层 JSON 和网关 HTML 包装，返回可直接展示的可读文本；客户端不要再对这段文本执行 JSON 解析

响应体

执行中：

{
  "id": "task_XVCPphL5ZWOr2iMpGhNkV32qRTj7MSUO",
  "task_id": "task_XVCPphL5ZWOr2iMpGhNkV32qRTj7MSUO",
  "object": "video",
  "model": "doubao-seedance-2.0-A",
  "status": "in_progress",
  "progress": 50,
  "created_at": 1787299277
}

生成成功：

{
  "id": "task_XVCPphL5ZWOr2iMpGhNkV32qRTj7MSUO",
  "task_id": "task_XVCPphL5ZWOr2iMpGhNkV32qRTj7MSUO",
  "object": "video",
  "model": "doubao-seedance-2.0-A",
  "status": "completed",
  "progress": 100,
  "created_at": 1787299277,
  "completed_at": 1787299581,
  "duration_secs": 5,
  "expires_at": 1790578352,
  "framespersecond": 24,
  "generate_audio": true,
  "ratio": "9:16",
  "resolution": "480p",
  "seed": 20260409,
  "output_format": "mp4",
  "execution_expires_after": 172800,
  "metadata": {
    "url": "https://upstream.example.com/task_XVCPphL5ZWOr2iMpGhNkV32qRTj7MSUO.mp4?signature=...",
    "upstream_created": true
  },
  "usage": {
    "prompt_tokens": 141034,
    "completion_tokens": 0,
    "total_tokens": 141034,
    "quota": 2789652,
    "amount": 5.579304,
    "currency": "CNY"
  }
}

usage 只在任务完成结算后返回，数值与账单里这条任务的扣费完全一致：usage.quota 是本次消耗的积分，usage.amount 是同一个积分按当前站点汇率折算的人民币金额，usage.total_tokens 是本次计费的视频 token 数。任务还在排队或生成中时不会返回 usage，此时不要按查询响应判断费用；需要核对扣费时，用同一个 id 在控制台账单中比对 usage.quota 与 usage.amount。

metadata.url 可能是带签名的上游地址，也可能由平台制品接口兜底。请按凭证处理，不要公开分享。成片生成后建议在 expires_at 之前下载或转存到你自己的对象存储。

视频制品与预览

除直接读取 metadata.url 外，也可以查询平台制品列表：

curl "$LOCOPAL_API_ORIGIN/v1/tasks/$LOCOPAL_TASK_ID/artifacts" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY"

任务完成后返回：

{
  "task_id": "task_XVCPphL5ZWOr2iMpGhNkV32qRTj7MSUO",
  "artifacts": [
    {
      "key": "video",
      "type": "video",
      "content_url": "https://locopalai.com/v1/tasks/task_XVCPphL5ZWOr2iMpGhNkV32qRTj7MSUO/artifacts/video/content?access=..."
    }
  ]
}

制品内容地址支持 Range 请求；播放器、浏览器预览和断点下载都可以直接使用。若客户端只读取 metadata.url，则继续使用原有逻辑，不需要改成制品接口。

生成失败：

{
  "id": "task_NlersigX6rIqiOjCwTFlgNmGMTwqt39K",
  "object": "video",
  "model": "doubao-seedance-2.0-D",
  "status": "failed",
  "progress": 100,
  "created_at": 1789971935,
  "error": {
    "code": "video_generation_failed",
    "message": "音频素材缓冲失败: 音频地址必须是 http(s)"
  },
  "metadata": {
    "submission_stage": "submitting",
    "upstream_created": false
  }
}

error.message 是平台整理后的最终失败文案。历史任务即使最初存的是嵌套 JSON，查询时也会返回归一化后的文本；调用方直接向用户展示该字段即可，不要在客户端再拼接或解析原始上游 JSON。

错误响应

查询不存在的任务 ID（或不属于当前账号的任务）返回 HTTP 400：

{ "code": "task_not_exist", "message": "task_not_exist", "data": null }

HTTP	响应	处理
`400`	`{"code":"task_not_exist","message":"task_not_exist","data":null}`	核对任务 ID 与创建任务时的账号
`401`	`Invalid token`	API Key 缺失、错误或已失效
`500`	任务查询失败	保存请求 ID，稍后继续查询原任务

状态处理

状态	客户端处理
`queued`	任务已进入队列，继续查询同一个任务 ID
`in_progress`	正在生成，更新进度和等待时间，不创建新任务
`completed`	读取 `metadata.url`，或调用 `/v1/videos/{task_id}/content` 下载成片；建议尽快转存
`failed`	展示一次 `error.code` 与 `error.message`，由用户决定是否重新提交
`unknown`	暂时无法判断状态，保留任务 ID 后稍后查询

客户端不要用固定等待秒数判断完成，也不要因为一次网络超时重复创建任务；建议 5～15 秒查询一次。

参考素材读取失败

错误指向 content[n].image_url、video_url 或包含 resource download failed 时，先按数组下标定位具体元素，再检查：

URL 能否从公网直接 GET 并返回 200；
是否跳转到登录页或依赖 Cookie、Referer、IP 白名单；
Content-Type 是否与文件真实格式一致；
临时签名 URL 在下载和处理期间是否仍然有效；
asset:// 素材是否属于当前账户且状态为 Active；
当前模型是否支持该素材类型和数量。

修正素材后重新创建任务。错误信息只需向用户显示一次可读原因，不要把多层转义 JSON 重复拼接展示。

并发、重试与计费

不同视频任务可以并发创建；
同一个创建响应必须使用同一个任务 ID 查询；
只有任务明确失败且用户主动重试时，才发起新的创建请求；
计费按模型、分辨率、时长和参考视频输入细分，以模型广场和最终账单为准；参数校验失败（400）表示请求未被受理，通常不产生生成任务费用。

想看什么	去哪一页
多图、参考视频、深度视频的能力边界与常见问题	多图与参考视频说明
从素材入库到视频提交的完整流程	人像素材与参考视频接入流程
素材分组、素材状态、真人授权	素材库接口
错误码速查	错误码与排查

查询视频任务

查询视频任务

认证方式

请求参数 · path

请求示例

下载视频

响应参数

响应体

视频制品与预览

错误响应

状态处理

参考素材读取失败

并发、重试与计费

相关文档

本页目录