MaaS-HL
公共信息
| 参数 | 描述 | 示例 |
|---|---|---|
| basePath | 调用mass api的基础路径，包含/v1/ai固定路径 | https://genaiapi.cloudsway.net/v1/ai |
| endpointPath | 调用mass api的生成的一段随机路径 | LPUqHEAjfonOmohV |
| AccessKey | 调用mass api的accessKey | RWxxxxxxxx0Gd |
| taskId | 异步处理视频任务的任务id | 1234abcd |
按照上面示例,最终请求接口的路径为 https://genaiapi.cloudsway.net/v1/ai/XXXXX/hailuo/video/generate
MaaS_HL_Video_i2v 图生视频
请求方法
POST
请求路径
{basePath}/{endpointPath}/hailuo/video/generate
请求header
| 参数 | 描述 | 示例 |
|---|---|---|
| Authorization | AccessKey Bearer ${AccessKey} |
Bearer RWXXXXXXX0Gd |
请求body
| 字段名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| prompt | string | 否 | 生成视频的描述。(注：最大支持2000字符)。 |
| promptOptimizer | promptOptimizer | 否 | 默认取值为true，模型会自动优化传入的prompt，以提升生成质量。如果需要更精确的控制，可以将此参数设置为false，模型将更加严格地遵循指令。此时建议提供更精细的prompt，以获得最佳效果。 |
| firstFrameImage | string | 是 | 模型将以此参数中传入的图片为首帧画面来生成视频。支持传入图片的data:image/jpeg;base64,{data}格式的 Base64 编码字符串，或可通过公网访问的 URL。传入此参数时支持将prompt设置为空字符串或不传入prompt，模型将自主决定画面如何演变。 传入图片需要满足以下条件： 1.格式为JPG/JPEG/PNG； 2.长宽比大于2:5、小于5:2； 3.短边像素大于300px； 4.大小不大于20MB。 |
返回值
| 字段名 | 类型 | 描述 |
|---|---|---|
| taskId | string | 任务ID |
示例
请求
curl --location --request POST 'https://genaiapi.cloudsway.net/v1/ai/XXXXX/hailuo/video/generate' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {YOUR_ACCESS_KEY}' \
--data-raw '{
"prompt": " ",
"promptOptimizer": true,
"firstFrameImage": "https://bpic.588ku.com/element_origin_min_pic/21/06/18/74907fcfaa474bb06b76a8b1c6ff917e.jpg"
}'
返回值
{
"taskId": "1896852590888419329"
}
MaaS_HL_Video_t2v （文生视频）
请求方法
POST
请求路径
{basePath}/{endpointPath}/hailuo/video/generate
请求header
| 参数 | 描述 | 示例 |
|---|---|---|
| Authorization | AccessKey Bearer ${AccessKey} |
Bearer RWXXXXXXX0Gd |
请求body
| 字段名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| prompt | string | 是 | 生成视频的描述。(注：最大支持2000字符)。 |
| promptOptimizer | promptOptimizer | 否 | 默认取值为true，模型会自动优化传入的prompt，以提升生成质量。如果需要更精确的控制，可以将此参数设置为false，模型将更加严格地遵循指令。此时建议提供更精细的prompt，以获得最佳效果。 |
| firstFrameImage | string | 否 | 模型将以此参数中传入的图片为首帧画面来生成视频。支持传入图片的data:image/jpeg;base64,{data}格式的 Base64 编码字符串，或可通过公网访问的 URL。传入此参数时支持将prompt设置为空字符串或不传入prompt，模型将自主决定画面如何演变。 传入图片需要满足以下条件： 1.格式为JPG/JPEG/PNG； 2.长宽比大于2:5、小于5:2； 3.短边像素大于300px； 4.大小不大于20MB。 |
返回值
| 字段名 | 类型 | 描述 |
|---|---|---|
| taskId | string | 任务ID |
示例
请求
curl --location --request POST 'https://genaiapi.cloudsway.net/v1/ai/XXXXX/hailuo/video/generate' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {YOUR_ACCESS_KEY}' \
--data-raw '{
"prompt": "女生落落大方，在风景如画的场景中微笑",
"promptOptimizer": true,
"firstFrameImage": " "
}'
返回值
{
"taskId": "1896852590888419329"
}
MaaS_HL_Video_i2v_live （图生视频立绘）
请求方法
POST
请求路径
{basePath}/{endpointPath}/hailuo/video/generate
请求header
| 参数 | 描述 | 示例 |
|---|---|---|
| Authorization | AccessKey Bearer ${AccessKey} |
Bearer RWXXXXXXX0Gd |
请求body
| 字段名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| prompt | string | 否 | 生成视频的描述。(注：最大支持2000字符)。 |
| promptOptimizer | promptOptimizer | 否 | 默认取值为true，模型会自动优化传入的prompt，以提升生成质量。如果需要更精确的控制，可以将此参数设置为false，模型将更加严格地遵循指令。此时建议提供更精细的prompt，以获得最佳效果。 |
| firstFrameImage | string | 是 | 模型将以此参数中传入的图片为首帧画面来生成视频。支持传入图片的data:image/jpeg;base64,{data}格式的 Base64 编码字符串，或可通过公网访问的 URL。传入此参数时支持将prompt设置为空字符串或不传入prompt，模型将自主决定画面如何演变。 传入图片需要满足以下条件： 1.格式为JPG/JPEG/PNG； 2.长宽比大于2:5、小于5:2； 3.短边像素大于300px； 4.大小不大于20MB。 |
返回值
| 字段名 | 类型 | 描述 |
|---|---|---|
| taskId | string | 任务ID |
示例
请求
curl --location --request POST 'https://genaiapi.cloudsway.net/v1/ai/XXXXX/hailuo/video/generate' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {YOUR_ACCESS_KEY}' \
--data-raw '{
"prompt": " ",
"promptOptimizer": true,
"firstFrameImage": "https://bpic.588ku.com/element_origin_min_pic/21/06/18/74907fcfaa474bb06b76a8b1c6ff917e.jpg"
}'
返回值
{
"taskId": "1896852590888419329"
}
MaaS_HL_Video_i2v_director （图生视频运镜）
请求方法
POST
请求路径
{basePath}/{endpointPath}/hailuo/video/generate
请求header
| 参数 | 描述 | 示例 |
|---|---|---|
| Authorization | AccessKey Bearer ${AccessKey} |
Bearer RWXXXXXXX0Gd |
请求body
| 字段名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| prompt | string | 否 | 生成视频的描述。(注：最大支持2000字符)。 一、支持插入运镜指令，实现运镜控制：运镜指令需以[ ]格式插入prompt中镜头应用处，标准运镜指令格式为[C1,C2,C3]，其中C表示不同类型运镜，共支持15种枚举运镜方式，具体可参考下方详情。为保证运镜效果，建议组合运镜指令不超过3个。 1.支持15种运镜方式（枚举值） （1） 左右移：[左移]、[右移] （2）左右摇：[左摇]、[右摇] （3）推拉：[推进]、[拉远] （4）升降：[上升]、[下降] （5）上下摇：[上摇]、[下摇] （6）变焦：[变焦推近]、[变焦拉远] （7）晃动：[晃动] （8）跟随：[跟随] （9）固定：[固定] 2、支持单一及组合运镜 （1）单一运镜：例如[左摇]，表示插入单一镜头； （2）多运镜同时生效：同一组内的镜头表示同时生效，如[左摇,右移]，表示插入两个组合镜头，且同时生效； （3）多运镜先后生效：插入在前的镜头指令，先生效。如在prompt描述“xxx[左摇]，xxx[右移] ” 表示：视频生成时，先运行左摇镜头，后运行右移镜头； 二、支持通过自然语言描述，实现运镜控制；使用指令内运镜名称，会提升运镜响应准确性。 三、 运镜指令与自然语言描述可同时生效。 |
| promptOptimizer | promptOptimizer | 否 | 默认取值为true，模型会自动优化传入的prompt，以提升生成质量。如果需要更精确的控制，可以将此参数设置为false，模型将更加严格地遵循指令。此时建议提供更精细的prompt，以获得最佳效果。 |
| firstFrameImage | string | 是 | 模型将以此参数中传入的图片为首帧画面来生成视频。支持传入图片的data:image/jpeg;base64,{data}格式的 Base64 编码字符串，或可通过公网访问的 URL。传入此参数时支持将prompt设置为空字符串或不传入prompt，模型将自主决定画面如何演变。 传入图片需要满足以下条件： 1.格式为JPG/JPEG/PNG； 2.长宽比大于2:5、小于5:2； 3.短边像素大于300px； 4.大小不大于20MB。 |
返回值
| 字段名 | 类型 | 描述 |
|---|---|---|
| taskId | string | 任务ID |
示例
请求
curl --location --request POST 'https://genaiapi.cloudsway.net/v1/ai/XXXXX/hailuo/video/generate' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {YOUR_ACCESS_KEY}' \
--data-raw '{
"prompt": " ",
"promptOptimizer": true,
"firstFrameImage": "https://bpic.588ku.com/element_origin_min_pic/21/06/18/74907fcfaa474bb06b76a8b1c6ff917e.jpg"
}'
返回值
{
"taskId": "1896852590888419329"
}
MaaS_HL_Video_t2v_director （文生视频运镜）
请求方法
POST
请求路径
{basePath}/{endpointPath}/hailuo/video/generate
请求header
| 参数 | 描述 | 示例 |
|---|---|---|
| Authorization | AccessKey Bearer ${AccessKey} |
Bearer RWXXXXXXX0Gd |
请求body
| 字段名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| prompt | string | 是 | 生成视频的描述。(注：最大支持2000字符)。 一、支持插入运镜指令，实现运镜控制：运镜指令需以[ ]格式插入prompt中镜头应用处，标准运镜指令格式为[C1,C2,C3]，其中C表示不同类型运镜，共支持15种枚举运镜方式，具体可参考下方详情。为保证运镜效果，建议组合运镜指令不超过3个。 1.支持15种运镜方式（枚举值） （1） 左右移：[左移]、[右移] （2）左右摇：[左摇]、[右摇] （3）推拉：[推进]、[拉远] （4）升降：[上升]、[下降] （5）上下摇：[上摇]、[下摇] （6）变焦：[变焦推近]、[变焦拉远] （7）晃动：[晃动] （8）跟随：[跟随] （9）固定：[固定] 2、支持单一及组合运镜 （1）单一运镜：例如[左摇]，表示插入单一镜头； （2）多运镜同时生效：同一组内的镜头表示同时生效，如[左摇,右移]，表示插入两个组合镜头，且同时生效； （3）多运镜先后生效：插入在前的镜头指令，先生效。如在prompt描述“xxx[左摇]，xxx[右移] ” 表示：视频生成时，先运行左摇镜头，后运行右移镜头； 二、支持通过自然语言描述，实现运镜控制；使用指令内运镜名称，会提升运镜响应准确性。 三、 运镜指令与自然语言描述可同时生效。 |
| promptOptimizer | promptOptimizer | 否 | 默认取值为true，模型会自动优化传入的prompt，以提升生成质量。如果需要更精确的控制，可以将此参数设置为false，模型将更加严格地遵循指令。此时建议提供更精细的prompt，以获得最佳效果。 |
| firstFrameImage | string | 否 | 模型将以此参数中传入的图片为首帧画面来生成视频。支持传入图片的data:image/jpeg;base64,{data}格式的 Base64 编码字符串，或可通过公网访问的 URL。传入此参数时支持将prompt设置为空字符串或不传入prompt，模型将自主决定画面如何演变。 传入图片需要满足以下条件： 1.格式为JPG/JPEG/PNG； 2.长宽比大于2:5、小于5:2； 3.短边像素大于300px； 4.大小不大于20MB。 |
返回值
| 字段名 | 类型 | 描述 |
|---|---|---|
| taskId | string | 任务ID |
示例
请求
curl --location --request POST 'https://genaiapi.cloudsway.net/v1/ai/XXXXX/hailuo/video/generate' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {YOUR_ACCESS_KEY}' \
--data-raw '{
"prompt": "女生落落大方，在风景如画的场景中微笑",
"promptOptimizer": true,
"firstFrameImage": " "
}'
返回值
{
"taskId": "1896852590888419329"
}
MaaS_HL_Video_s2v（主体生视频）
请求方法
POST
请求路径
{basePath}/{endpointPath}/hailuo/video/generate
请求header
| 参数 | 描述 | 示例 |
|---|---|---|
| Authorization | AccessKey Bearer ${AccessKey} |
Bearer RWXXXXXXX0Gd |
请求body
| 字段名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| prompt | string | 否 | 生成视频的描述。(注：最大支持2000字符) |
| promptOptimizer | promptOptimizer | 否 | 默认取值为true，模型会自动优化传入的prompt，以提升生成质量。如果需要更精确的控制，可以将此参数设置为false，模型将更加严格地遵循指令。此时建议提供更精细的prompt，以获得最佳效果。 |
| firstFrameImage | string | 否 | 模型将以此参数中传入的图片为首帧画面来生成视频。支持传入图片的data:image/jpeg;base64,{data}格式的 Base64 编码字符串，或可通过公网访问的 URL。传入此参数时支持将prompt设置为空字符串或不传入prompt，模型将自主决定画面如何演变。 传入图片需要满足以下条件： 1.格式为JPG/JPEG/PNG； 2.长宽比大于2:5、小于5:2； 3.短边像素大于300px； 4.大小不大于20MB。 |
| type | string | 是 | 主体类型，目前仅支持"character"，即人物面部主体。 |
| image | string | 是 | 主体参考图的data:image/jpeg;base64,{data}格式的Base64 编码字符串，或可通过公网访问的 URL，以字符串形式存储在数组中（暂时数组长度仅支持为 1，即单图参考）。 主体参考图片尺寸需小于20MB，格式支持jpg、jpeg、png。 注：图片中需要包含有效主体信息，否则视频生成过程将会失败（任务创建时不会受阻），此情况下将会在查询接口中返回视频生成任务失败状态。 |
返回值
| 字段名 | 类型 | 描述 |
|---|---|---|
| taskId | string | 任务ID |
示例
请求
curl --location --request POST 'https://genaiapipre.cloudsway.net/v1/ai/XXXXX/hailuo/video/generate' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {YOUR_ACCESS_KEY}' \
--data-raw '{
"prompt": "镜头缓缓移动，跟随清澈的溪流穿过茂密的森林，阳光透过树叶，斑驳的光影在水面上跳动，伴随轻柔的流水声",
"subjectReference": [
{
"type": "character",
"image": [
"https://bpic.588ku.com/element_origin_min_pic/21/06/18/74907fcfaa474bb06b76a8b1c6ff917e.jpg"
]
}
]
}'
返回值
{
"taskId": "1896852590888419329"
}
获取fileId
请求方法
GET
请求路径
{basePath}/{endpointPath}/hailuo/video/task/{taskId}
请求header
| 参数 | 描述 | 示例 |
|---|---|---|
| Authorization | AccessKey Bearer ${AccessKey} |
Bearer RWXXXXXXX0Gd |
返回值
| 字段名 | 类型 | 描述 |
|---|---|---|
| taskId | string | 此次被查询的任务ID |
| status | string | 任务状态，包括以下状态： Preparing-准备中 Queueing-队列中 Processing-生成中 Success-成功 Fail-失败 |
| fileId | string | 任务成功后，该字段返回生成视频对应的文件ID |
| videoWidth | Integer | 任务成功后，该字段将返回生成视频的横边像素数。 |
| videoHeight | Integer | 任务成功后，该字段将返回生成视频的竖边像素数。 |
示例
请求
curl --location --request GET 'https://genaiapi.cloudsway.net/v1/ai/xxxxxxxxxx/hailuo/video/task/{taskID}' \
--header 'Authorization: Bearer {YOUR_ACCESS_KEY}'
返回值
{
"status": "Preparing",
"file_id": "",
"task_id": "244785605570723",
"base_resp": {
"status_msg": "success",
"status_code": 0
},
"video_width": 0,
"video_height": 0
}
获取视频url
请求方法
GET
请求路径
{basePath}/{endpointPath}/hailuo/video/file?taskId={taskID}&fileId={fileID}
请求header
| 参数 | 描述 | 示例 |
|---|---|---|
| Authorization | AccessKey Bearer ${AccessKey} |
Bearer RWXXXXXXX0Gd |
返回值
| 字段名 | 类型 | 描述 |
|---|---|---|
| taskId | string | 此次被查询的任务ID |
| createdAt | string | 创建文件时的 Unix 时间戳，以秒为单位。 |
| filename | string | 文件的名称。 |
| purpose | Integer | 文件的使用目的。 |
| mediaUrl | Integer | 视频url |
| expireTime | string | 文件过期时间，以秒为单位。 |
示例
请求
curl --location --request GET 'https://genaiapi.cloudsway.net/v1/ai/xxxxxx/hailuo/video/file?taskId={taskID}&fileId={fileID}' \
--header 'authorization: Bearer {YOUR_ACCESS_KEY}'
返回值
{
"fileId": "243456265392387",
"createdAt": 1740990443,
"filename": "output.mp4",
"purpose": "video_generation",
"mediaUrl": "https://public-cdn-video-data-algeng.oss-cn-wulanchabu.aliyuncs.com/inference_output%2Fvideo%2F2025-03-03%2F39dc4a78-d61a-481e-ad09-03fa8d149d0f%2Foutput.mp4?Expires=1741347299&OSSAccessKeyId=LTAI5tAmwsjSaaZVA6cEFAUu&Signature=%2FBltvbcKIHHDKgHvy651PcV2rzk%3D",
"expireTime": 1741022843
}