Create Task

POST /v1/tasks

Submit a generation task. You get a taskId back right away while the model keeps working in the background — then poll Get Task Detail or wait for the callback to fetch the result.

Headers

Authorization Bearer YOUR_API_KEY required

Account API key. Required on every request.

Content-Type application/json optional

Optional. The body is always parsed as JSON; if sent, only application/json is accepted (charset is fine) — anything else returns 415.

Idempotency-Key order-42-submit optional

Optional. Idempotency key, up to 255 bytes. Retries with the same key under the same account create the task only once; replays return the original taskId.

The full rules for these headers (authentication scope, content type, idempotency scenarios) are documented in the Unified Async API Introduction.

Request body

</> Generate Code

model string required

The model you want to run. Browse the model pages for available names.

example happyhorse-1-0

route string optional

Model route (e.g. beta, ext) for models that expose multiple routes with different pricing or upstream capacity. See the model routes section below.

example ext

input object required

The model's business parameters; fields are defined per model.

callback object optional

Terminal-notification config; omit to skip callbacks and poll yourself. See the callback section below.

url string required

Required when callback is present; HiAPI POSTs here when terminal. Must be a valid http(s) URL.

when string optional

Currently only final — both success and fail fire a callback.

default final

storage string optional

Output storage tier: temp (default, kept ~7 days) or persistent (kept long-term, billed by size). Insufficient balance or exceeding your storage cap silently downgrades to temp; the actual tier is reflected on the task detail response.

default temp example persistent

Do not put callback fields in input

Do not put any callback / webhook / notify field inside input, or the request is rejected. Callbacks are configured only via the top-level callback — see the callback section below.

input fields depend on the model

The prompt / duration / resolution above are illustrative. Each model accepts different input fields — refer to the relevant model page.

Keep outputs longer

Outputs are temporary by default and expire after about 7 days. Set "storage": "persistent" to keep them long-term, or promote them later — see Output Storage.

Model routes (route)

Some models expose multiple routes (e.g. beta, ext) with different pricing or upstream capacity. Select one with the optional top-level route parameter — the preferred spelling over the legacy @ suffix:

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

• Passing model gpt-image-2/text-to-image with route: "ext" is equivalent to the suffixed name gpt-image-2/text-to-image@ext; the legacy @ suffix keeps working
• Omitting route, or sending "" / null / "default", all mean the model’s default route
• An unknown route fails fast with 400 INVALID_REQUEST whose message lists the available routes
• A route that conflicts with an @ suffix already present in model (e.g. x@ext + route: "official") is also a 400
• On the task detail, a task submitted with route echoes the field back and model holds the resolved full name (x@ext); the route value participates in the idempotency hash, so the same Idempotency-Key with a different route returns 422

Success response (HTTP 200)

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR"
  }
}

• taskId looks like tk-hiapi- + 26 chars, 35 chars total.
• Returned as soon as the task is created — generation continues in the background.

Failure response

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

code is the HTTP status; error_code is the business error code (enum under status information). Common synchronous failures: invalid body (400), insufficient balance (402), non-JSON Content-Type (415). When the platform is temporarily unavailable it may return HTTP 503 — retry later with backoff.

Callbacks (Webhook)

Provide callback.url when creating a task and HiAPI notifies you with a POST on terminal state — no polling needed. Request format, signature verification, delivery retries and idempotency: see Callbacks in the introduction.