方法与鉴权
腾讯云视频任务查询使用 POST https://vod.tencentcloudapi.com/，Action 为 DescribeTaskDetail，Version 为 2018-07-17，使用与创建请求相同的腾讯云 API3 TC3 签名。
本目录暂不提供已确认可用的本站腾讯云视频查询入口。 不要向旧的 /tencent-vod/v1/query/{task_id} 轮询，也不要把腾讯云任务 ID 填入本站通用视频查询路径。需要本站调用方式请先看接入状态。
查询请求与 ID 来源
TaskId 来自 CreateAigcVideoTask 返回的 Response.TaskId。在腾讯云原生查询中它位于 JSON 请求体，并不是 URL 路径参数。
| 字段 | 类型·要求 | 含义、默认与限制 |
|---|---|---|
TaskId | String；必填 | 必填，原样使用创建响应中的 Response.TaskId；不要拼接或转换前缀。 |
SubAppId | Integer；可选，条件见说明 | 与创建任务的点播应用一致。2023-12-25 起开通点播的用户访问应用资源时必须提供，即使通用表标为可选。 |
腾讯云该查询动作最多查询最近 3 天内提交的任务。这与临时产物的有效期是不同限制；不要等到文件过期才首次查询任务。
外层返回与任务状态
| 字段 | 类型·要求 | 含义、默认与限制 |
|---|---|---|
Response.TaskType | String；按任务阶段返回 | 本页视频任务为 AigcVideoTask；根据实际 TaskType 读取对应对象。 |
Response.Status | String；按任务阶段返回 | 外层状态：WAITING / PROCESSING / FINISH / ABORTED。FINISH 不自动表示生成成功。 |
Response.AigcVideoTask | AigcVideoTask；按任务阶段返回 | 仅 TaskType=AigcVideoTask 时有值；包含任务错误、进度和产物。 |
Response.RequestId | String；按任务阶段返回 | 本次查询请求 ID，用于定位错误；不是创建返回的 TaskId。 |
WAITING：等待处理，可继续查询。PROCESSING：处理中，可继续查询。FINISH：处理结束，继续检查AigcVideoTask的错误码和结果。ABORTED：任务已终止，停止自动轮询并处理终止原因。
可每 5～10 秒查询一次，遇到限流或临时网络错误逐渐延长间隔，并设置业务等待上限。这是客户端建议，不是服务限流或生成时间承诺。停止轮询、网络超时都不等于任务已取消。
AigcVideoTask 内层返回
只有 Response.TaskType 为 AigcVideoTask 时，按下面的路径读取。接口返回错误对象时先处理 API 错误，不要假设任务对象必然存在。
| 字段 | 类型·要求 | 含义、默认与限制 |
|---|---|---|
Response.AigcVideoTask.TaskId | String；按任务阶段返回 | 原始视频任务 ID。 |
Response.AigcVideoTask.Status | String；按任务阶段返回 | 内层状态只有 PROCESSING / FINISH。FINISH 时还需检查 ErrCode、ErrCodeExt、Message 和产物。 |
Response.AigcVideoTask.ErrCode | Integer；按任务阶段返回 | 任务错误码，非 0 表示错误；不能仅依赖外层 HTTP 状态判断生成成功。 |
Response.AigcVideoTask.ErrCodeExt | String；按任务阶段返回 | 扩展错误码，如 RequestLimitExceeded、InvalidParameterValue、ContentModerationFailed、ModelGenerateFailed、OperationCanceled、TaskTimeout。 |
Response.AigcVideoTask.Message | String；按任务阶段返回 | 任务错误信息；字段名是 Message。 |
Response.AigcVideoTask.Progress | Integer；按任务阶段返回 | 整数 0～100，只用于进度展示。 |
Response.AigcVideoTask.Input | AigcVideoTaskInput；按任务阶段返回 | 任务输入信息；展示或记录前应过滤业务敏感数据。 |
Response.AigcVideoTask.Output | AigcVideoTaskOutput；按任务阶段返回 | 任务输出对象，读取 FileInfos 文件数组；失败或未完成时不要假设有视频。 |
Response.AigcVideoTask.SessionId | String；按任务阶段返回 | 创建时的去重标识。 |
Response.AigcVideoTask.SessionContext | String；按任务阶段返回 | 创建时传入的业务上下文。 |
成功判断应同时考虑：任务结束、没有任务错误，并有适合当前业务的有效产物。`FINISH` 或 `Progress=100` 单独都不等于视频生成成功。 ErrCode 非 0 时按失败处理；错误码为 0 但产物缺失、类型异常或仍有错误说明时，保留脱敏响应定位，不要自动重新创建。
视频生成任务读取 AigcVideoTask.Output.FileInfos，不要读取 AigcImageTask。图片任务、视频任务和 3D/场景任务的结果不可互换。
产物与下载
下面的 Output 位于 Response.AigcVideoTask 内；文件数组在任务未完成或失败时不保证含有有效视频。
| 字段 | 类型·要求 | 含义、默认与限制 |
|---|---|---|
Output.FileInfos[].StorageMode | String；按任务阶段返回 | Temporary / Permanent。保存方式决定后续保留策略。 |
Output.FileInfos[].ExpireTime | String；按任务阶段返回 | ISO 8601 过期时间；按实际返回值及时保存产物。 |
Output.FileInfos[].FileType | String；按任务阶段返回 | 实际文件类型，如 mp4/flv；检查类型后处理，不要强制把所有文件改成 .mp4。 |
Output.FileInfos[].FileUrl | String；按任务阶段返回 | 生成媒体的访问地址。不要向此地址发送青云TOP API Key 或腾讯云签名凭据。 |
Output.FileInfos[].FileContent | String；按任务阶段返回 | UsageType=position_info 时的内容字符串，不是视频下载链接。 |
Output.FileInfos[].FileId | String；按任务阶段返回 | Permanent 时有效，点播媒体 ID；不是生成任务 ID。 |
Output.FileInfos[].UsageType | String；按任务阶段返回 | 部分模型返回 3D 场景、点云、网格或图片等其他产物。须按用途处理，不保证每一项都是视频。 |
Temporary 存储的官方说明为临时链接有效 7 天；仍应按实际 ExpireTime 及时保存。Permanent 会返回点播 FileId，保留期限受点播存储及过期设置影响。不能承诺所有 FileUrl 永久有效，也不能假设重新查询一定会刷新链接。
拿到有效 FileUrl 后，用普通 HTTP 客户端下载二进制，检查 HTTP 状态和内容类型，再保存到你的存储。不要向文件域名附加青云TOP API Key 或腾讯云签名凭据。下载失败时保留 TaskId、FileType、ExpireTime 与错误；任务仍在可查询期内可再查同一 ID，过期后联系对应服务支持，不要无条件重建。
常见错误与处理
- 返回 HTML：请求没有得到 JSON 任务响应。核对域名、方法和完整路径，不能将 HTTP 200 当成生成成功。
RequestLimitExceeded：减小并发、延迟查询；已有任务不要重复创建。InvalidParameterValue/InvalidParameter.MediaFormat：核对版本、字段类型及素材格式。ContentModerationFailed：根据内容规则调整输入，不要自动重试同一内容。ModelGenerateFailed/TaskTimeout：保留 TaskId、RequestId、ErrCodeExt 和 Message，再判断是否需要提交新任务。- 找不到任务：检查任务来源、点播应用与 3 天查询窗口。不要用请求追踪 ID 代替 TaskId。
本页不提供本站回调、取消或批量查询承诺。腾讯云原生账号的事件通知配置也不会自动变成本站 webhook。