Create Task

POST /v1/tasks

Submit an async generation task. It returns a taskId immediately and does not wait for generation to finish; then poll Get Task Detail or wait for the terminal callback.

Headers

Authorization Bearer YOUR_API_KEY required

Account API key. Required on every request.

Content-Type application/json required

The request body is JSON.

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

Target HiAPI model name.

example happyhorse-1-0

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

Success response (HTTP 200)

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

taskId looks like tk-hiapi- + 26 chars, 35 chars total.
Returns on successful creation, without waiting for generation to finish.

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.