统一异步接口介绍

/v1/tasks 是图片、视频、音频等所有异步生成模型的统一入口：一套请求格式、一套状态机、一套回调。换模型，只需要换 model 和 input。

提交任务

POST /v1/tasks 传入 model 与 input，立即返回 taskId，生成在后台继续。
获取结果

轮询 GET /v1/tasks/:id 直到任务进入终态；或在创建时配置 callback.url，终态时由 HiAPI 主动推送结果。

input 的字段由各模型自行定义，以对应模型页为准；model / route / callback 等公共参数的完整说明见创建任务。

端点说明

所有请求使用统一 Base URL：

https://api.hiapi.ai

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

请求头

三个端点共用下列请求头；其中 Content-Type 与 Idempotency-Key 仅用于 POST /v1/tasks。

Authorization Bearer YOUR_API_KEY 必填

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

Content-Type application/json 可选

可选。请求体固定按 JSON 解析；如携带，仅接受 application/json。

Idempotency-Key order-42-submit 可选

可选。幂等键，同账户同键的重试只创建一次任务。

认证

在 Authorization 头携带账号 API Key，格式为 Bearer YOUR_API_KEY。API Key 在控制台创建与管理，见认证。

内容类型

Content-Type 可填可不填——请求体始终按 JSON 解析。规则一张表说清：

你发送的 Content-Type	行为
不携带该头	✅ 正常处理
`application/json`（可带 `charset` 等参数）	✅ 正常处理
其他取值（`text/plain`、表单类型等）	❌ 返回 `415 UNSUPPORTED_MEDIA_TYPE`

幂等键

给 POST /v1/tasks 带上 Idempotency-Key（任意 UTF-8 字符串，最长 255 字节），网络超时、客户端自动重试就不会重复建任务、重复扣费。幂等范围是 API Key 所属账户，中途轮换密钥不受影响。

场景	平台行为
首次提交	正常创建任务，返回 `taskId`
同键 + 相同请求体重放	不再建任务，直接返回首次的 `taskId`，响应头带 `Idempotent-Replay: true`
同键 + 不同请求体	`422 IDEMPOTENCY_KEY_MISMATCH`，检查你的键生成逻辑，不要重试
同键 + 首次请求仍在处理中	`409 IDEMPOTENCY_KEY_PROCESSING`，按 `Retry-After`（5 秒）稍后重试
距首次提交超过 24 小时	键已过期，按新请求处理

这里管的是提交方向的幂等（你重复提交，平台只建一次）；回调投递方向的幂等（HiAPI 可能重复投递，你按 taskId 去重）见下方回调说明，两者互相独立。

状态信息

一次调用的结果分三层看：HTTP 状态码（这次请求有没有被接受）→ 业务错误码（为什么被拒或失败）→ 任务状态（异步生成进行到哪一步）。

HTTP 状态码

状态码	含义
`200`	成功（任务详情即使 `status=fail` 也返回 `200`，失败信息在 body 的 `error` 里）
`400`	请求不合法，见下方 `error_code`
`402`	账户余额不足，任务未创建、不扣费；充值后重试
`404`	任务不存在或不属于当前账号
`409`	幂等键冲突：同键的首次请求仍在处理中，按 `Retry-After` 稍后重试
`415`	`Content-Type` 不是 `application/json`；改为 `application/json` 或去掉该头后重试
`422`	幂等键不匹配：同键但请求体不同，检查键的生成逻辑，不要重试
`503`	平台暂时不可用，按指数退避稍后重试

业务错误码

POST /v1/tasks 的同步失败响应（error_code）与终态任务的 error.code 共用下列枚举；标注「仅创建期」的码只出现在同步响应中，不会出现在终态任务的 error.code 里。

code	含义	处置建议
`INVALID_REQUEST`	请求体不合法（缺字段 / 类型错误 / `callback.url` 不合法 / 模型不接受该 `input`），或幂等键超 255 字节 / 非 UTF-8	检查请求体，不要重试相同请求
`UNSUPPORTED_MEDIA_TYPE`	`Content-Type` 携带了非 `application/json` 的取值（HTTP `415`，仅创建期）	改为 `application/json` 或去掉该头后重试
`INSUFFICIENT_QUOTA`	账户余额不足（HTTP `402`，仅创建期），任务未创建、不扣费	充值后重试；可在控制台设置余额提醒
`IDEMPOTENCY_KEY_PROCESSING`	同 `Idempotency-Key` 的首次请求仍在处理中（HTTP `409`，仅创建期）	按 `Retry-After`（5 秒）重试，见幂等键
`IDEMPOTENCY_KEY_MISMATCH`	同 `Idempotency-Key` 但请求体不同（HTTP `422`，仅创建期）	检查键的生成逻辑，不要重试
`MODEL_UNAVAILABLE`	模型当前不可用（未启用、无权限、暂时不可用）	短暂后重试，或换可用模型
`TASK_FAILED`	任务失败	可重试一次；反复出现请联系平台
`TASK_TIMEOUT`	任务超时	可重试
`STORAGE_UNAVAILABLE`	任务产物存储异常	可重试；反复出现请联系平台

失败响应统一形如：

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

任务状态枚举

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

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

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

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

回调说明

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

轮询 — 创建任务后，按一定间隔请求 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 自行做幂等处理。

这里说的是回调投递的幂等（HiAPI 重复投递，你按 taskId 去重）；提交方向的幂等（你重复提交，平台只建一次任务）由 Idempotency-Key 请求头负责，两者互相独立。