• 简体中文
  • 查询与下载(可灵统一格式)

    提交任务后,用提交响应中的 id 调用查询接口轮询,任务成功后直接拿到成片直链——查询与取片一次完成,无需再调其他下载接口。

    端点

    GET /kling-video/v1/videos/{task_id}

    task_id 为提交响应中的 id(见提交任务 · 响应体)。

    请求示例

    轮询直到 SUCCESS / FAILURE,取 result_url 下载:

    cURL
    Python
    Node.js
    # 查询任务状态与直链
    curl https://api-model.shuntianchuang.cn/kling-video/v1/videos/task_xxxxxxxx \
      -H "Authorization: Bearer sk-你的令牌"
    
    # 任务 SUCCESS 后,result_url 即成片直链,直接下载
    curl -o output.mp4 "result_url 字段返回的视频地址"

    响应体

    字段说明
    code恒为 "success"(业务错误走统一错误包络,见失败与错误处理)
    message恒为空串
    data.task_id任务 id
    data.status四值:QUEUED 排队中 → IN_PROGRESS 生成中 → SUCCESS 成功 / FAILURE 失败
    data.progress"0%" ~ "100%";SUCCESS 恒为 "100%"
    data.result_url仅 SUCCESS 非空:成片直链,即取即用
    data.fail_reason仅 FAILURE 非空:失败原因

    任务状态由平台后台自动推进,不依赖客户轮询;轮询只是为了拿到 result_url。

    状态机:

    提交 ──> QUEUED ──> IN_PROGRESS ──> SUCCESS(result_url 可下载)
                            └────────> FAILURE(fail_reason)

    响应示例

    // 生成中
    {
      "code": "success",
      "message": "",
      "data": {
        "task_id": "task_xxxxxxxx",
        "status": "IN_PROGRESS",
        "progress": "40%",
        "result_url": "",
        "fail_reason": ""
      }
    }
    // 成功
    {
      "code": "success",
      "message": "",
      "data": {
        "task_id": "task_xxxxxxxx",
        "status": "SUCCESS",
        "progress": "100%",
        "result_url": "https://example.com/output.mp4",
        "fail_reason": ""
      }
    }

    下载成片

    result_url 为成片直链:浏览器直接打开即可预览 / 保存;代码里 HTTP GET 下载、网页 <video> 播放、前端 fetch 读取均可。

    直链有时效,请在生成后尽快下载取用,不要把直链当作长期有效的分发链接。

    失败与错误处理

    • 任务失败:data.status 为 FAILURE,data.fail_reason 给出可读原因(如素材不合规);失败任务不计费;
    • 任务不存在(HTTP 404):
    {
      "code": "task_not_found",
      "message": "Task not found (request id: …)",
      "data": null
    }