Create Task

POST Base URL: https://api.hiapi.ai /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. Exact model IDs are listed in the model catalog at https://www.hiapi.ai/docs/models.json, which is also what the model pages are generated from.

example happyhorse-1.0

route string optional

Model route (e.g. beta, ext) for models that expose multiple routes with different pricing or 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 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": { ... } }

Routes published in the model catalog:

Model	Available routes
gpt-image-2/text-to-image	default, beta, ext
gpt-image-2/image-to-image	default, ext
seedance-2.0	default, ext
gpt-image-2.5-flare/text-to-image	default
gpt-image-2.5-flare/image-to-image	default
gpt-image-2.5-sunburst/text-to-image	default
gpt-image-2.5-sunburst/image-to-image	default

• The 2.5 series registers capability-specific models on the default route, plus a pro route under the family name: send model gpt-image-2.5-flare with route: "pro". The bare family name without a capability suffix and without route is not a registered model and fails with 400
• Passing model gpt-image-2/text-to-image with route: "ext" selects the ext route
• 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
• On the task detail, a task submitted with route echoes the field back and model holds the resolved full name; the route value participates in the idempotency hash, so the same Idempotency-Key with a different route returns 422

The authoritative list of exact model IDs and their routes is models.json, the same catalog the model pages are generated from.

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.