创建任务
/v1/tasks 提交一个生成任务。你会立即拿到 taskId，模型在后台继续生成——随后通过获取任务详情轮询，或等待回调来获取结果。
Authorization Bearer YOUR_API_KEY 必填 账号 API Key，所有请求必填。
Content-Type application/json 可选 可选。请求体固定按 JSON 解析；如携带，仅接受 application/json（可带 charset），其他取值返回 415。
Idempotency-Key order-42-submit 可选 可选。幂等键，最长 255 字节。同账户同键的重试只创建一次任务，重放返回首次 taskId。
请求头的完整规则（认证范围、内容类型、幂等键的各种场景）见统一异步接口介绍。
model string 必填 要调用的模型名称，可在模型页查看支持的模型。
route string 可选 模型线路（如 beta、ext），用于同一模型有多条定价/上游容量不同线路的场景，详见下方模型线路说明。
input object 必填 该模型的业务参数对象。字段由各模型自行定义，参考对应模型页。
callback object 可选 终态通知配置；为空则不回调，由调用方自行查询。详见下方回调说明。
url string 必填 callback 存在时必填；任务终态后向该 URL 发起 POST，须为合法 http(s) URL。
when string 可选 当前仅支持 final，即 success / fail 均回调。
storage string 可选 产物存储档位：temp（默认，保留约 7 天）或 persistent（长期保存，按大小计费）。余额不足或超出存储上限会静默降级为 temp；实际生效档位见任务详情响应。
模型线路（route）
Section titled “模型线路（route）”部分模型提供多条线路（如 beta、ext），定价或上游容量不同。用可选的顶层 route 参数选择线路——这是推荐写法，替代旧的 @ 后缀：
{ "model": "gpt-image-2/text-to-image", "route": "ext", "input": { ... } }model传gpt-image-2/text-to-image并配route: "ext"，等价于带后缀的gpt-image-2/text-to-image@ext；旧的@后缀写法继续可用- 不传
route，或传""/null/"default"，均指该模型的默认线路 - 线路不存在时快速失败，返回
400 INVALID_REQUEST，报错消息会列出可用线路 route与model中已带的@后缀矛盾（如x@ext+route: "official"）同样返回400- 任务详情中，用
route提交的任务会回显该字段，且model返回解析后的全名（x@ext）；route参与幂等 hash，同一Idempotency-Key配不同route会返回422
成功响应（HTTP 200）
Section titled “成功响应（HTTP 200）”{ "code": 200, "message": "success", "data": { "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR" }}taskId形如tk-hiapi-+ 26 位字符，全长 35 字符。- 任务创建后立即返回，生成在后台继续。
{ "code": 400, "message": "invalid request", "data": null, "error_code": "INVALID_REQUEST"}code 为 HTTP 状态码，error_code 为业务错误码（枚举见状态信息）。常见同步失败：请求体不合法（400）、余额不足（402）、Content-Type 非 JSON（415）。平台暂时不可用时可能返回 HTTP 503，请按退避策略稍后重试。
回调（Webhook）
Section titled “回调（Webhook）”创建任务时提供 callback.url，任务终态时 HiAPI 主动 POST 通知你，免去轮询。请求格式、签名校验、投递重试与幂等详见介绍页的回调说明。