通用任务查询

异步模型任务和异步应用任务提交成功后,均使用本接口查询平台任务状态和最终结果。

请求路径:GET /api/v1/tasks/{task_id}

鉴权:Authorization: Bearer <API_KEY>

task_id 取自创建任务或异步应用接口成功响应中的 data.task_id。任务只能由创建它的 API Key 所属租户和用户查询。

请求示例

GET /api/v1/tasks/task_xxxxxxxxxxxx
Authorization: Bearer <YOUR_API_KEY>

也可以使用 cURL:

curl -X GET "https://<域名>/api/v1/tasks/task_xxxxxxxxxxxx" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

响应字段

所有成功响应的业务数据均在 data 中。

字段类型说明
task_idstring平台任务 ID。
modelstring创建任务时使用的平台模型编码。
typestring任务类型,例如 image、video、audio、text 或 app。
call_typestringsync 或 async。
statusstringpending、processing、completed、failed 或 cancelled。
created_atstring \null创建时间,ISO 8601 格式。
resultobject \array仅任务完成时返回。实际结果字段和结构以所调用模型或应用的文档为准。
usageobject正常完成时返回,含 token 用量及 points_cost 实扣点数。
completed_atstring \null正常完成时返回,ISO 8601 格式。
response_time_msnumber \null正常完成时返回,处理耗时(毫秒)。
errorobject任务处理失败或结果不可用时可能返回,包含 code、message。
storageobject请求中使用 storage 且转存成功时返回。
storage_errorobject请求中使用 storage 且转存失败时可能返回。

响应示例

处理中

{
  "code": 1,
  "msg": "success",
  "data": {
    "task_id": "task_xxxxxxxxxxxx",
    "model": "h3-video",
    "type": "video",
    "call_type": "async",
    "status": "processing",
    "created_at": "2026-08-01T10:00:00+08:00"
  }
}

已完成

{
  "code": 1,
  "msg": "success",
  "data": {
    "task_id": "task_xxxxxxxxxxxx",
    "model": "h3-video",
    "type": "video",
    "call_type": "async",
    "status": "completed",
    "created_at": "2026-08-01T10:00:00+08:00",
    "completed_at": "2026-08-01T10:01:20+08:00",
    "response_time_ms": 80000,
    "result": {
      "video_url": "https://example.com/output.mp4"
    },
    "usage": {
      "input_tokens": 0,
      "output_tokens": 0,
      "total_tokens": 0,
      "points_cost": 400
    }
  }
}

失败

{
  "code": 1,
  "msg": "success",
  "data": {
    "task_id": "task_xxxxxxxxxxxx",
    "model": "h3-video",
    "type": "video",
    "call_type": "async",
    "status": "failed",
    "created_at": "2026-08-01T10:00:00+08:00",
    "error": {
      "code": "task_failed",
      "message": "任务处理失败,请检查参数后重试。"
    }
  }
}

轮询与回调

  • 未传 callback_url 时,使用本接口轮询。建议从提交后 2 秒开始,每次间隔 2 至 5 秒;任务处于 completed、failed 或 cancelled 时停止轮询。
  • 提交时传入 callback_url 后,平台会在任务成功或失败时向该地址发送 POST 通知;仍建议保留本查询接口作为回调未收到时的补偿查询。
  • 查询接口不产生新的扣费。实际扣费以任务完成时返回的 usage.points_cost 为准。

任务列表和取消任务的接口说明见 [公共参数与 storage](api-integration.md)。

同类文章