Hailuo 02 API 接入文档
使用 VezAPI 密钥接入 Hailuo 02。下列操作共用同一个账号余额和鉴权方式。
https://api.vezapi.com请求头使用 Authorization: Bearer YOUR_VEZAPI_KEY。每次提交使用唯一的 Idempotency-Key,查询同一笔提交时才复用。
Hailuo Pro 图生视频
/api/v1/jobs/createTask模型标识: hailuo/02-image-to-video-pro
| 参数 | 类型 | 说明与限制 |
|---|---|---|
model必填 | string | 用于生成任务的模型名称。必填字段。 - 该接口必须使用 `hailuo/02-image-to-video-pro` 模型 可选值: 默认: |
callBackUrl可选 | string | 接收生成任务完成通知的回调 URL。可选配置,生产环境建议使用。 - 任务生成完成后,系统会向该 URL 以 POST 方式推送任务状态和结果 - 回调内容包含生成内容的 URL 及任务相关信息 - 你的回调接口需支持接收 POST 请求及 JSON 格式的请求体 - 也可选择调用任务详情接口,主动轮询任务状态 |
input必填 | object | 生成任务的输入参数 |
input.prompt必填 | string | 描述目标视频动画效果的文本提示词(最大长度:1500 字符)
|
input.image_url必填 | string | 待动画化的输入图像 URL(需为上传后的文件 URL,而非文件内容;支持的格式:image/jpeg、image/png、image/webp;最大文件大小:10.0MB) |
input.end_image_url可选 | string | 可选参数,作为视频最后一帧的图像 URL(需为上传后的文件 URL,而非文件内容;支持的格式:image/jpeg、image/png、image/webp;最大文件大小:10.0MB) |
input.prompt_optimizer可选 | boolean | 是否启用模型的提示词优化功能(布尔值:true/false) |
input.nsfw_checker可选 | boolean | 默认 false。为 false 时不额外进行内容过滤,结果由模型直接返回。 |
请求示例
curl -X POST 'https://api.vezapi.com/api/v1/jobs/createTask' \
-H 'Authorization: Bearer YOUR_VEZAPI_KEY' \
-H 'Idempotency-Key: your-unique-request-id' \
-H 'Content-Type: application/json' \
-d '{
"model": "hailuo/02-image-to-video-pro",
"input": {
"prompt": "Cinematic wide shot: A colossal starship drifts silently above the rings of Saturn, its metallic hull reflecting streaks of cosmic light. The camera pushes closer, revealing thousands of illuminated windows like a floating city. Smaller fighter crafts dart across the frame, leaving neon trails as they maneuver through the vastness of space. A sudden burst of thrusters scatters asteroid fragments in slow motion, glowing faintly as they collide and drift apart.",
"image_url": "https://example.com/input.png"
}
}'返回值与错误
HTTP 200
请求成功
| 参数 | 类型 | 说明与限制 |
|---|---|---|
code可选 | integer | Status code of the request. The HTTP status is 200 even when the request fails, so always check this field: 200 means success; any other value means the request failed and msg describes the reason. Common values: 401 invalid or missing API key; 402 insufficient credits; 429 rate limit exceeded; 422 or 500 the request could not be processed (read msg and check your parameters before retrying). 可选值: |
msg可选 | string | Response message, error description upon failure |
data必填 | object | |
data.taskId必填 | string | The task ID can be used with the "Get Task Details" endpoint to query the task status. |
Hailuo Standard 图生视频
/api/v1/jobs/createTask模型标识: hailuo/02-image-to-video-standard
| 参数 | 类型 | 说明与限制 |
|---|---|---|
model必填 | string | 用于生成任务的模型名称。必填字段。 - 该接口必须使用 `hailuo/02-image-to-video-standard` 模型 可选值: 默认: |
callBackUrl可选 | string | 接收生成任务完成通知的回调 URL。可选配置,生产环境建议使用。 - 任务生成完成后,系统会向该 URL 以 POST 方式推送任务状态和结果 - 回调内容包含生成内容的 URL 及任务相关信息 - 你的回调接口需支持接收 POST 请求及 JSON 格式的请求体 - 也可选择调用任务详情接口,主动轮询任务状态 |
input必填 | object | 生成任务的输入参数 |
input.prompt必填 | string | 描述待生成视频效果的文本提示词(最大长度:1500 字符)
|
input.image_url必填 | string | 作为视频第一帧的图像 URL(需为上传后的文件 URL,而非文件内容;支持的格式:image/jpeg、image/png、image/webp;最大文件大小:10.0MB) |
input.end_image_url可选 | string | 可选参数,作为视频最后一帧的图像 URL(需为上传后的文件 URL,而非文件内容;支持的格式:image/jpeg、image/png、image/webp;最大文件大小:10.0MB) |
input.duration必填 | string | 必填。视频时长(秒):6 或 10。 可选值: |
input.resolution必填 | string | 必填。生成视频的分辨率 可选值: |
input.prompt_optimizer可选 | boolean | 是否启用模型的提示词优化功能(布尔值:true/false) |
input.nsfw_checker可选 | boolean | 默认 false。为 false 时不额外进行内容过滤,结果由模型直接返回。 |
请求示例
curl -X POST 'https://api.vezapi.com/api/v1/jobs/createTask' \
-H 'Authorization: Bearer YOUR_VEZAPI_KEY' \
-H 'Idempotency-Key: your-unique-request-id' \
-H 'Content-Type: application/json' \
-d '{
"model": "hailuo/02-image-to-video-standard",
"input": {
"prompt": "Epic aerial shot: A lone samurai stands atop a jagged mountain peak as a storm of sakura petals is swept across the wind. Behind him, the sky is split in two — half daylight, half night. The shot pulls back to reveal that the mountain is actually the curved back of a sleeping dragon that spans across the horizon. Lightning crackles in the distance as the dragon'\''s eye slowly opens, glowing with ancient magic. The samurai doesn’t flinch; he lowers his straw hat and places his hand on the hilt of his blade.",
"image_url": "https://example.com/input.png",
"duration": "10",
"resolution": "768P"
}
}'返回值与错误
HTTP 200
请求成功
| 参数 | 类型 | 说明与限制 |
|---|---|---|
code可选 | integer | Status code of the request. The HTTP status is 200 even when the request fails, so always check this field: 200 means success; any other value means the request failed and msg describes the reason. Common values: 401 invalid or missing API key; 402 insufficient credits; 429 rate limit exceeded; 422 or 500 the request could not be processed (read msg and check your parameters before retrying). 可选值: |
msg可选 | string | Response message, error description upon failure |
data必填 | object | |
data.taskId必填 | string | The task ID can be used with the "Get Task Details" endpoint to query the task status. |
Hailuo Pro 文生视频
/api/v1/jobs/createTask模型标识: hailuo/02-text-to-video-pro
| 参数 | 类型 | 说明与限制 |
|---|---|---|
model必填 | string | 用于生成任务的模型名称。必填字段。 - 该接口必须使用 `hailuo/02-text-to-video-pro` 模型 可选值: 默认: |
callBackUrl可选 | string | 接收生成任务完成通知的回调 URL。可选配置,生产环境建议使用。 - 任务生成完成后,系统会向该 URL 以 POST 方式推送任务状态和结果 - 回调内容包含生成内容的 URL 及任务相关信息 - 你的回调接口需支持接收 POST 请求及 JSON 格式的请求体 - 也可选择调用任务详情接口,主动轮询任务状态 |
input必填 | object | 生成任务的输入参数 |
input.prompt必填 | string | 用于视频生成的文本提示词(最大长度:1500 字符)
|
input.prompt_optimizer可选 | boolean | 是否启用模型的提示词优化功能(布尔值:true/false) |
input.nsfw_checker可选 | boolean | 默认 false。为 false 时不额外进行内容过滤,结果由模型直接返回。 |
请求示例
curl -X POST 'https://api.vezapi.com/api/v1/jobs/createTask' \
-H 'Authorization: Bearer YOUR_VEZAPI_KEY' \
-H 'Idempotency-Key: your-unique-request-id' \
-H 'Content-Type: application/json' \
-d '{
"model": "hailuo/02-text-to-video-pro",
"input": {
"prompt": "High top angle wide mid close-up tracking shot, flying very fast two meters high over prehistoric ferns and moss-covered ground, dominated by a real young boy (pink t-shirt, pink shorts, white shoes, white long socks), with his back to the camera, body stretched out, gliding smoothly forward, flying in the air, casting a clear shadow on the terrain below. His legs and body are high above the surface, his feet not touching the ground, soaring in a Superman pose. The background is a vast Jurassic valley, filled with dense, ancient jungle vegetation and towering cycads. In the distance, rugged volcanic mountains rise with a winding path cutting through. Massive, slow-moving sauropods graze far off on the horizon. Large, fluffy white clouds float in the vibrant blue sky. Strong dynamic motion blur adds a vivid sense of high-speed flight and deep cinematic perspective. Realistic image –raw."
}
}'返回值与错误
HTTP 200
请求成功
| 参数 | 类型 | 说明与限制 |
|---|---|---|
code可选 | integer | Status code of the request. The HTTP status is 200 even when the request fails, so always check this field: 200 means success; any other value means the request failed and msg describes the reason. Common values: 401 invalid or missing API key; 402 insufficient credits; 429 rate limit exceeded; 422 or 500 the request could not be processed (read msg and check your parameters before retrying). 可选值: |
msg可选 | string | Response message, error description upon failure |
data必填 | object | |
data.taskId必填 | string | The task ID can be used with the "Get Task Details" endpoint to query the task status. |
Hailuo Standard 文生视频
/api/v1/jobs/createTask模型标识: hailuo/02-text-to-video-standard
| 参数 | 类型 | 说明与限制 |
|---|---|---|
model必填 | string | 用于生成任务的模型名称。必填字段。 - 该接口必须使用 `hailuo/02-text-to-video-standard` 模型 可选值: 默认: |
callBackUrl可选 | string | 接收生成任务完成通知的回调 URL。可选配置,生产环境建议使用。 - 任务生成完成后,系统会向该 URL 以 POST 方式推送任务状态和结果 - 回调内容包含生成内容的 URL 及任务相关信息 - 你的回调接口需支持接收 POST 请求及 JSON 格式的请求体 - 也可选择调用任务详情接口,主动轮询任务状态 |
input必填 | object | 生成任务的输入参数 |
input.prompt必填 | string | 用于视频生成的文本描述(最大长度:1500 字符)
|
input.duration必填 | string | 必填。视频时长(秒):6 或 10。 可选值: |
input.prompt_optimizer可选 | boolean | 是否启用模型的提示词优化功能(布尔值:true/false) |
input.nsfw_checker可选 | boolean | 默认 false。为 false 时不额外进行内容过滤,结果由模型直接返回。 |
请求示例
curl -X POST 'https://api.vezapi.com/api/v1/jobs/createTask' \
-H 'Authorization: Bearer YOUR_VEZAPI_KEY' \
-H 'Idempotency-Key: your-unique-request-id' \
-H 'Content-Type: application/json' \
-d '{
"model": "hailuo/02-text-to-video-standard",
"input": {
"prompt": "A llama and a raccoon battle it out in an intense table tennis match, inside a roaring Olympic stadium. Slow-mo, wild angles, full comedy mode.",
"duration": "6"
}
}'返回值与错误
HTTP 200
请求成功
| 参数 | 类型 | 说明与限制 |
|---|---|---|
code可选 | integer | Status code of the request. The HTTP status is 200 even when the request fails, so always check this field: 200 means success; any other value means the request failed and msg describes the reason. Common values: 401 invalid or missing API key; 402 insufficient credits; 429 rate limit exceeded; 422 or 500 the request could not be processed (read msg and check your parameters before retrying). 可选值: |
msg可选 | string | Response message, error description upon failure |
data必填 | object | |
data.taskId必填 | string | The task ID can be used with the "Get Task Details" endpoint to query the task status. |
任务状态与回调
异步任务请保存返回的 taskId。调用 GET /api/v1/jobs/recordInfo?taskId=... 查询,或在创建时设置 callBackUrl。只有任务所属账号可以查询任务或基于任务创建派生资源。
超时可能表示请求已经受理。请在控制台查看原请求,不要自动新建任务。回调可能重试并重复到达,请使用 X-VezAPI-Event-Id 去重。
文件、日志与计费
生成媒体通常随上游保留 14 天,上传文件在 24 小时后失效。请在过期前保存所需文件。VezAPI 仅流式转发已登记资源,不提供永久作品库。请求日志保留两个自然月。
调用前预留积分,最终按实际优惠扣分 1:1 结算。用量不明时暂停新付费请求。若保护其他任务预留后余额不足以结算,会保留待结算记录,补足余额后再扣费;模型用量不会将钱包扣成负数。按时长计价的输入文件由服务端读取时长,读取失败时不提交模型任务。