• 简体中文
  • 获取视频生成任务状态

    查询视频生成任务的进度与结果,与创建视频生成任务(通用任务格式)配套使用。

    NOTE

    Sora 格式(/v1/videos)的查询响应与本端点不同:使用小写状态值,完成后经 /content 端点下载视频。可灵、即梦官方格式的查询端点见各自页面,响应结构与本端点相同。豆包 / Seedance 与 MiniMax-H3 渠道直接使用本端点(参数差异见各自页面)。

    端点

    GET /v1/video/generations/{task_id}

    认证

    请求头携带 Bearer 令牌:

    Authorization: Bearer sk-你的令牌

    路径参数

    参数类型必填说明
    task_idstring是创建接口返回的任务 ID

    响应体

    查询响应为统一任务 JSON:

    {
      "code": "success",
      "data": {
        "task_id": "task_xxxxxxxx",
        "status": "SUCCESS",
        "progress": "100%",
        "result_url": "https://xxxx/video.mp4",
        "fail_reason": ""
      }
    }
    data 字段说明
    task_id任务 ID
    status状态流转:NOT_START(已提交待处理)→ QUEUED / SUBMITTED(排队、已提交)→ IN_PROGRESS(生成中)→ SUCCESS(成功)或 FAILURE(失败)
    progress进度百分比字符串,如 "50%"
    result_url成功后的视频下载直链,建议及时下载转存(产物链接约 1 小时后失效)
    fail_reason失败原因

    任务不存在时返回 400:

    {
      "code": "task_not_exist",
      "message": "task not exist",
      "data": null
    }

    轮询示例

    建议每 10 秒轮询一次,SUCCESS 后从 data.result_url 取视频直链下载。

    cURL
    Python
    Node.js
    curl https://api-model.shuntianchuang.cn/v1/video/generations/task_xxxxxxxx \
      -H "Authorization: Bearer sk-你的令牌"

    计费按任务完成时的实际用量结算(失败自动退还)。