介绍

/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。

幂等重试（Idempotency-Key）

POST /v1/tasks 支持可选请求头 Idempotency-Key（任意 UTF-8 字符串，最长 255 字节）。幂等范围是 API Key 所属账户：同账户下用同一个键重试提交（即使中途轮换了密钥），只会创建一次任务，重放请求直接返回首次的 taskId，响应头带 Idempotent-Replay: true——网络超时、客户端自动重试不再重复建任务、重复扣费。

重试必须重发完全相同的请求体；同键不同请求体返回 422 IDEMPOTENCY_KEY_MISMATCH
首次请求仍在处理中时返回 409 IDEMPOTENCY_KEY_PROCESSING，按 Retry-After（5 秒）稍后重试
键保留 24 小时，之后同一键视为新请求
不带该头时行为完全不变

错误码明细见下方业务错误码。

模型与参数

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

模型线路（route）

部分模型提供多条线路（如 pro、ext），定价或上游容量不同。用可选的顶层 route 参数选择线路——这是推荐写法，替代旧的 @ 后缀：

{ "model": "gpt-image-2/text-to-image", "route": "pro", "input": { ... } }

model 传 gpt-image-2/text-to-image 并配 route: "pro"，等价于带后缀的 gpt-image-2/text-to-image@pro；旧的 @ 后缀写法继续可用
不传 route，或传 "" / null / "default"，均指该模型的默认线路
线路不存在时快速失败，返回 400 INVALID_REQUEST，报错消息会列出可用线路
route 与 model 中已带的 @ 后缀矛盾（如 x@ext + route: "official"）同样返回 400
任务详情中，用 route 提交的任务会回显该字段，且 model 返回解析后的全名（x@pro）；route 参与幂等 hash，同一 Idempotency-Key 配不同 route 会返回 422

回调说明

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

轮询 — 创建任务后，按一定间隔请求 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 请求头负责，两者互相独立。

状态码

任务状态枚举

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

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

HTTP 状态码

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

业务错误码

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

code	含义	处置建议
`INVALID_REQUEST`	请求体不合法（缺字段 / 类型错误 / `callback.url` 不合法 / 模型不接受该 `input`），或幂等键超 255 字节 / 非 UTF-8	检查请求体，不要重试相同请求
`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"
}

状态机

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

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