创建任务

POST /v1/tasks

提交一个生成任务。你会立即拿到 taskId，模型在后台继续生成——随后通过获取任务详情轮询，或等待回调来获取结果。

请求头

Authorization Bearer YOUR_API_KEY 必填

账号 API Key，所有请求必填。

Content-Type application/json 必填

请求体为 JSON。

Idempotency-Key order-42-submit 可选

幂等键，最长 255 字节。同账户同键的重试只创建一次任务，重放返回首次 taskId。详见介绍页的幂等重试说明。

请求体

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

# 提交异步任务，成功立即返回 taskId（不等待生成完成）
# 把 YOUR_API_KEY 换成你的账号 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

# 业务参数对象，字段随模型而定（见对应模型页）
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"
  }
}
''')

# 提交异步任务，成功立即返回 taskId（不等待生成完成）
resp = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json"},
    json=payload,
)
print(resp.json())  # 成功返回 { code, message, data: { taskId } }

// 提交异步任务，成功立即返回 taskId（不等待生成完成）
// 把 YOUR_API_KEY 换成你的账号 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()); // 成功返回 { code, message, data: { taskId } }

model string 必填

要调用的模型名称，可在模型页查看支持的模型。

示例 happyhorse-1-0

route string 可选

模型线路（如 pro、ext），用于同一模型有多条定价/上游容量不同线路的场景。推荐用本参数替代旧的 model@线路后缀写法：model "x" + route "pro" 等价于 model "x@pro"。不传 / 传 "default" 均指默认线路。线路不存在时返回 400 并列出可用线路；与 model 中已带的 @ 后缀矛盾同样返回 400。

示例 pro

input object 必填

该模型的业务参数对象。字段由各模型自行定义，参考对应模型页。

callback object 可选

终态通知配置；为空则不回调，由调用方自行查询。

url string 必填

callback 存在时必填；任务终态后向该 URL 发起 POST，须为合法 http(s) URL。

when string 可选

当前仅支持 final，即 success / fail 均回调。

默认 final

storage string 可选

产物存储档位：temp（默认，保留约 7 天）或 persistent（长期保存，按大小计费）。余额不足或超出存储上限会静默降级为 temp；实际生效档位见任务详情响应。

默认 temp 示例 persistent

成功响应（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 为业务错误码（枚举见状态码）。平台暂时不可用时可能返回 HTTP 503，请按退避策略稍后重试。