本页目录
Hailuo 2.3 API
通过一套异步 API 创建 Hailuo 2.3 文生视频和图生视频任务；需要更低延迟的图生视频时可使用 Hailuo 2.3 Fast。
REST API · v1 · 异步任务
完成第一次调用
使用唯一 Idempotency-Key 创建任务，保存返回的 task ID，然后轮询到成功或失败。
- 1
创建 API Key
在 imya 账户设置中生成一枚密钥。
- 2
创建任务
选择 Hailuo 2.3 或 Fast，并提交输入。
- 3
获取结果
轮询 task ID，直到任务成功或失败。
身份验证与幂等
API Key 通过 Bearer Token 发送。每个生成 POST 还必须带唯一 Idempotency-Key，安全重试不会重复创建任务或扣费。
Authorization: Bearer YOUR_IMYA_API_KEY
Content-Type: application/json
Idempotency-Key: YOUR_UNIQUE_REQUEST_KEY创建视频生成任务
创建异步 Hailuo 任务，并返回服务端根据本次请求实时计算的 credits_reserved。
/v1/videos/generations# Text to video (Hailuo 2.3)
curl https://imya.ai/v1/videos/generations \
-H "Authorization: Bearer YOUR_IMYA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: hailuo-t2v-order-001" \
-d '{
"model": "hailuo-2.3",
"prompt": "A paper boat crossing a rain-soaked neon street",
"duration": 6,
"resolution": "768p",
"prompt_optimizer": true
}'
# Image to video (Hailuo 2.3 Fast)
curl https://imya.ai/v1/videos/generations \
-H "Authorization: Bearer YOUR_IMYA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: hailuo-i2v-order-001" \
-d '{
"model": "hailuo-2.3-fast",
"prompt": "Slow camera push-in with warm moving light",
"image_url": "https://cdn.example.com/first-frame.jpg",
"duration": 6,
"resolution": "1080p"
}'旧 Beta 兼容接口
现有接入可继续使用 POST /api/video/generate + x-api-key，但生成 POST 现在也必须携带 Idempotency-Key，确保重试不会重复扣费。新接入应使用 /v1/videos/generations。
curl https://imya.ai/api/video/generate \
-H "x-api-key: YOUR_IMYA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: legacy-hailuo-order-001" \
-d '{
"modelKey": "hailuo-2-3-standard-t2v",
"prompt": "A paper boat crossing a rain-soaked neon street",
"resolution": "720p",
"outputDurationSec": 6,
"promptExtend": true
}'查询任务
返回最新任务状态、最终积分、生成的 MP4 或净化后的错误。请勿快于每 5 秒轮询一次。视频结果链接可能是临时的，请及时下载；生产 Beta 暂不保证 API 视频保留 7/30 天。
/v1/tasks/{task_id}curl https://imya.ai/v1/tasks/task_0123456789abcdef0123456789abcdef \
-H "Authorization: Bearer YOUR_IMYA_API_KEY"请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| model | string | 是 | hailuo-2.3 或 hailuo-2.3-fast。 |
| prompt | string | 是 | 生成说明，最多 5,000 字符。 |
| image_url | string | 条件必填 | 公开 HTTPS 首帧。Fast 必填；标准文生视频不传。 |
| duration | number | 否 | 6 或 10 秒，默认 6 秒。 |
| resolution | string | 否 | 768p 或 1080p；1080p 只支持 6 秒。 |
| prompt_optimizer | boolean | 否 | 是否优化提示词，默认 true。 |
返回结构
{
"id": "task_0123456789abcdef0123456789abcdef",
"status": "pending",
"model": "hailuo-2.3",
"credits_reserved": 225
}{
"id": "task_0123456789abcdef0123456789abcdef",
"status": "succeeded",
"model": "hailuo-2.3",
"credits_used": 225,
"data": [
{
"url": "https://media.example.com/generated/example.mp4"
}
]
}实时积分计费
服务端会根据模型、工作流、分辨率、时长和 API Key 所属用户的当前套餐计算 credits_reserved。返回示例中的数字只用于展示结构；客户端必须使用本次响应返回的值，不要缓存或自行写死 Hailuo 价格。
任务状态
pending任务已接收，正在等待处理。
processing模型正在生成视频。
succeeded生成完成，data 中包含 MP4。
failed生成失败，请读取净化后的 error 对象。
错误码
400缺少 Idempotency-Key 或 JSON 格式错误。
401API Key 缺失或无效。
402账户积分不足。
403API 账户已停用。
409同一幂等键被用于不同请求体。
413请求体超过 64 KiB。
422模型、提示词、图片、时长或分辨率无效。
429达到速率或并发任务上限。
5xx本次请求无法完成或提交。
接入前想先测试 Hailuo？
打开 Hailuo 2.3 在线工具，比较 Fast、标准、文字和图片输入。
在线试用 Hailuo 2.3