介绍

/v1/tasks 是图片 / 视频 / 音频等所有异步生成模型的统一入口。无论使用哪种模型，都通过同一组端点提交任务、查询状态、接收终态回调：提交后先拿到 taskId，再轮询任务详情或等待回调获取最终产物。

接口说明

所有请求使用统一 Base URL：

https://api.hiapi.ai

Method	Path	用途
`POST`	`/v1/tasks`	创建任务，返回 `taskId`
`GET`	`/v1/tasks`	获取任务列表（分页，按创建时间倒序）
`GET`	`/v1/tasks/:id`	获取任务详情：状态、产物或失败原因

认证

所有请求在 Authorization 头携带账号 API Key：

Authorization Bearer YOUR_API_KEY 必填

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

Content-Type application/json 必填

请求体为 JSON。

任务必须属于 API Key 所在账号；跨账号查询返回 404。

模型与参数

创建任务时通过 model 指定 HiAPI 对外模型名，业务参数放在 input 对象里。input 的字段由各模型自行定义，请参考对应模型页的参数说明。

回调说明

异步任务支持两种获取结果的方式：

轮询 — 创建任务后，按一定间隔请求 GET /v1/tasks/:id，直到 status 进入终态。
回调（Webhook） — 创建任务时提供 callback.url，任务进入终态（success 或 fail）时由 HiAPI 主动向该 URL 发起 POST。

回调请求：

Method：POST，Content-Type：application/json
Body：与 GET /v1/tasks/:id 的 data 字段完全一致（即任务详情对象）
callback.when 当前仅支持 final（success / fail 均回调）

签名（可选，推荐启用）

在 HiAPI 控制台账号设置页填写「Webhook 签名密钥」(共享密钥，16–256 字符；留空表示不签名)。

未填写：回调请求不附带签名头。
已填写：每次回调附带
- X-HiAPI-Timestamp：Unix 秒（字符串）
- X-HiAPI-Signature：hex( HMAC_SHA256(secret, timestamp + "." + body) )

接收方校验（Python 伪代码）：

import hmac, hashlib

ts   = request.headers["X-HiAPI-Timestamp"]
sig  = request.headers["X-HiAPI-Signature"]
body = request.raw_body  # 原始字节，未经 JSON 解析

expected = hmac.new(
    secret.encode(),
    (ts + "." + body).encode(),
    hashlib.sha256,
).hexdigest()

assert hmac.compare_digest(expected, sig), "bad signature"
# 推荐：拒绝 abs(now - int(ts)) > 5 分钟 的请求，防重放

重试与幂等

项目	行为
入队时机	任务进入 `success` 或 `fail` 时入队一次
成功判定	接收方返回 HTTP 2xx
失败重试	非 2xx / 超时 / 网络错误按立即 → +1 分钟 → +5 分钟 → +20 分钟重试，共最多 4 次
终态	4 次仍未成功后不再重试，不影响任务自身状态

终态回调「至少送达一次」，不保证「恰好一次」。接收方需按 taskId 自行做幂等处理。

状态码

任务状态枚举

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

终态只有 success / fail，二者不互相转换；同一 taskId 一旦进入终态，结果固定。

HTTP 状态码

状态码	含义
`200`	成功（任务详情即使 `status=fail` 也返回 `200`，失败信息在 body 的 `error` 里）
`400`	请求不合法，见下方 `error_code`
`404`	任务不存在或不属于当前账号
`503`	平台暂时不可用，按指数退避稍后重试

业务错误码

POST /v1/tasks 的同步失败响应（error_code）与终态任务的 error.code 共用下列枚举：

code	含义	处置建议
`INVALID_REQUEST`	请求体不合法（缺字段 / 类型错误 / `callback.url` 不合法 / 模型不接受该 `input`）	检查请求体，不要重试相同请求
`MODEL_UNAVAILABLE`	模型当前不可用（未启用、无权限、暂时不可用）	短暂后重试，或换可用模型
`TASK_FAILED`	任务失败	可重试一次；反复出现请联系平台
`TASK_TIMEOUT`	任务超时	可重试
`STORAGE_UNAVAILABLE`	任务产物存储异常	可重试；反复出现请联系平台

失败响应统一形如：

{
  "code": 400,
  "message": "invalid request",
  "data": null,
  "error_code": "INVALID_REQUEST"
}

状态机

   POST /v1/tasks ──► queued ──► handling ──► archiving ──► success  (终态)
       (200 / taskId)              │             │
                                   ▼             ▼
                                  fail          fail   (终态)

   进入 success / fail 时触发回调（若设置了 callback.url）