获取任务详情

GET /v1/tasks/:id

路径参数 :id 为创建任务时返回的 tk-hiapi- taskId。常用于轮询。

请求头

Authorization Bearer YOUR_API_KEY 必填

账号 API Key，所有请求必填。

任务必须属于 API Key 所在账号，跨账号查询返回 404——请求头完整规则见统一异步接口介绍。

路径参数

</> 生成代码

id string 必填

创建任务时返回的 taskId，前缀 tk-hiapi-。

示例 tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR

轮询建议

• 创建任务后建议先等 2–3 秒再发起第一次查询；之后每 3–5 秒查询一次，生成较慢的任务（如视频）可放宽到 5–10 秒。
• status 进入 success / fail 即可停止轮询：终态不可逆，同一 taskId 的结果固定，无需再查（状态机见任务状态枚举）。
• 收到 success 后尽快下载 output[].url——注意 expireAt 过期时间；需要长期保存可在创建时传 storage: "persistent"，或事后转持久存储。
• 生产环境建议配置回调获取终态通知，把轮询作为兜底。
• 收到 503 时按指数退避稍后重试。

字段说明

字段	类型	说明
taskId	string	任务 ID，前缀固定 tk-hiapi-
model	string	解析后的模型全名。用 route 参数提交的任务返回 base@线路（如 gpt-image-2/text-to-image@ext）；否则与创建时传入的模型名一致
route	string	仅当任务用显式 route 参数提交时出现，回显提交时的原值
status	string	状态枚举，见下
created	number	任务创建时间（Unix 秒）
completed	number	进入终态的 Unix 秒；非终态固定为 0
output	array	仅 status == success 时出现
error	object	仅 status == fail 时出现，结构 { code, message }

状态枚举

status	含义	是否返回 output
queued	已入队，尚未开始	否
handling	处理中	否
archiving	处理完成，产物准备中	否
success	终态：完成，产物可用	是
fail	终态：失败	否，返回 error

output[] 字段

字段	类型	说明
url	string	资源 URL，可直接下载
type	string	产物类型，见下
expireAt	number	资源可访问截止时间（Unix 秒）；过期前请完成下载或转存

常见 type（可扩展）：video、image、audio、first_frame、last_frame、thumbnail。output 始终为数组，同一任务可能同时返回多个 type（如 video + first_frame）。

成功响应（status = success）

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
    "model": "happyhorse-1-0",
    "status": "success",
    "created": 1777282033,
    "completed": 1777282099,
    "output": [
      {
        "url": "https://cdn.hiapi.ai/tasks/.../video.mp4",
        "type": "video",
        "expireAt": 1777886899
      },
      {
        "url": "https://cdn.hiapi.ai/tasks/.../first_frame.jpg",
        "type": "first_frame",
        "expireAt": 1777886899
      }
    ]
  }
}

非终态响应（如 status = archiving）

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "archiving",
    "created": 1777282033,
    "completed": 0
  }
}

失败响应（status = fail）

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "fail",
    "created": 1777282033,
    "completed": 1777282099,
    "error": {
      "code": "TASK_FAILED",
      "message": "task failed"
    }
  }
}

error.code 取值见状态码。

404

任务不存在或不属于当前账号：

{
  "code": 404,
  "message": "task not found",
  "data": null
}