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 required

The request body is JSON.

Idempotency-Key order-42-submit 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. See Idempotent retries on the Introduction page.

Request body

POST https://api.hiapi.ai/v1/tasks

# Create an async task — returns taskId immediately (generation runs async)
# Replace YOUR_API_KEY with your account API key
curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "happyhorse-1-0",
  "callback": {
    "url": "https://example.com/hiapi/callback",
    "when": "final"
  },
  "input": {
    "prompt": "a cyan glass data center entrance",
    "duration": 5,
    "resolution": "720p"
  }
}'

import requests, json

# Business params — fields vary by model (see the model page)
payload = json.loads(r'''
{
  "model": "happyhorse-1-0",
  "callback": {
    "url": "https://example.com/hiapi/callback",
    "when": "final"
  },
  "input": {
    "prompt": "a cyan glass data center entrance",
    "duration": 5,
    "resolution": "720p"
  }
}
''')

# Create an async task — returns taskId immediately (generation runs async)
resp = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json"},
    json=payload,
)
print(resp.json())  # Returns { code, message, data: { taskId } }

// Create an async task — returns taskId immediately (generation runs async)
// Replace YOUR_API_KEY with your account API key
const resp = await fetch("https://api.hiapi.ai/v1/tasks", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "happyhorse-1-0",
  "callback": {
    "url": "https://example.com/hiapi/callback",
    "when": "final"
  },
  "input": {
    "prompt": "a cyan glass data center entrance",
    "duration": 5,
    "resolution": "720p"
  }
}),
});
console.log(await resp.json()); // Returns { code, message, data: { taskId } }

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. pro, ext) for models that expose multiple routes with different pricing or upstream capacity. Preferred over the legacy model@route suffix: model "x" + route "pro" equals model "x@pro". Omitted / "default" both mean the default route. An unknown route is rejected with a 400 listing the available routes; a route that conflicts with an @ suffix already present in model is also a 400.

example pro

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.

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

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 codes). When the platform is temporarily unavailable it may return HTTP 503 — retry later with backoff.