Skip to content

MaaS-HL

Common Information

Parameter Description Example
basePath The base path for calling the mass API, includes the fixed path/v1/ai https://genaiapi.cloudsway.net/v2/ai
endpointPath A randomly generated path segment for calling the mass API
AccessKey The access key for calling the mass API RWxxxxxxxx0Gd
taskId The task ID for asynchronous image processing tasks 1234abcd

MaaS_HL_Video_i2v （image to video）

Request method

POST

Request path

{basePath}/{endpointPath}/hailuo/video/generate

Request header

Parameter Description Example
Authorization AccessKey
Bearer ${AccessKey}		 Bearer RWXXXXXXX0Gd

Request body

Parameter Type Required Description
prompt string No Description of the Generated Video: (Note: Maximum supported length is 2000 characters.)
promptOptimizer promptOptimizer No The default value is set to true, allowing the model to automatically optimize the input prompt to enhance generation quality. For more precise control, you can set this parameter to false, prompting the model to adhere strictly to instructions. In this case, it is recommended to provide a more detailed prompt to achieve the best results.
firstFrameImage string Yes The model will use the image provided in this parameter as the initial frame for generating the video. It supports images in the format of a Base64 encoded string, such as data:image/jpeg;base64,{data}, or a publicly accessible URL. When this parameter is used, the prompt can be left as an empty string or omitted, allowing the model to independently determine the evolution of the frames.
The image must meet the following conditions:
1. Format: JPG/JPEG/PNG
2. Aspect ratio between 2:5 and 5:2
3. Short side with more than 300px
4. Size not exceeding 20MB.

Response

Parameter Type Description
taskId string TaskID

Example

Request

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"
}'

Response

{
    "taskId": "1896852590888419329"
}

MaaS_HL_Video_t2v （text to video）

Request method

POST

Request path

{basePath}/{endpointPath}/hailuo/video/generate

Request header

Parameter Description Example
Authorization AccessKey
Bearer ${AccessKey}		 Bearer RWXXXXXXX0Gd

Request body

Parameter Type Required Description
prompt string Yes Description of the Generated Video: (Note: Maximum supported length is 2000 characters.)
promptOptimizer promptOptimizer No The default value is set to true, allowing the model to automatically optimize the input prompt to enhance generation quality. For more precise control, you can set this parameter to false, prompting the model to adhere strictly to instructions. In this case, it is recommended to provide a more detailed prompt to achieve the best results.
firstFrameImage string No The model will use the image provided in this parameter as the initial frame for generating the video. It supports images in the format of a Base64 encoded string, such as data:image/jpeg;base64,{data}, or a publicly accessible URL. When this parameter is used, the prompt can be left as an empty string or omitted, allowing the model to independently determine the evolution of the frames.
The image must meet the following conditions:
1. Format: JPG/JPEG/PNG
2. Aspect ratio between 2:5 and 5:2
3. Short side with more than 300px
4. Size not exceeding 20MB.

Response

Parameter Type Description
taskId string TaskID

Example

Request

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": "  "
}'

Response

{
    "taskId": "1896852590888419329"
}

MaaS_HL_Video_i2v_live （image to video live）

Request method

POST

Request path

{basePath}/{endpointPath}/hailuo/video/generate

Request header

Parameter Description Example
Authorization AccessKey
Bearer ${AccessKey}		 Bearer RWXXXXXXX0Gd

Request body

Parameter Type Required Description
prompt string No Description of the Generated Video: (Note: Maximum supported length is 2000 characters.)
promptOptimizer promptOptimizer No The default value is set to true, allowing the model to automatically optimize the input prompt to enhance generation quality. For more precise control, you can set this parameter to false, prompting the model to adhere strictly to instructions. In this case, it is recommended to provide a more detailed prompt to achieve the best results.
firstFrameImage string Yes The model will use the image provided in this parameter as the initial frame for generating the video. It supports images in the format of a Base64 encoded string, such as data:image/jpeg;base64,{data}, or a publicly accessible URL. When this parameter is used, the prompt can be left as an empty string or omitted, allowing the model to independently determine the evolution of the frames.
The image must meet the following conditions:
1. Format: JPG/JPEG/PNG
2. Aspect ratio between 2:5 and 5:2
3. Short side with more than 300px
4. Size not exceeding 20MB.

Response

Parameter Type Description
taskId string TaskID

Example

Request

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"
}'

Response

{
    "taskId": "1896852590888419329"
}

MaaS_HL_Video_i2v_director （image to video director）

Request method

POST

Request path

{basePath}/{endpointPath}/hailuo/video/generate

Request header

Parameter Description Example
Authorization AccessKey
Bearer ${AccessKey}		 Bearer RWXXXXXXX0Gd

Request body

Parameter Type Required Description
prompt string No Description for generating video. (Note: Maximum support of 2000 characters).
I. Supports insertion of camera movement instructions for camera control: Camera movement instructions should be inserted into the prompt in the [ ] format at the point of camera application. The standard format is [C1,C2,C3], where C represents different types of camera movements, supporting 15 enumerated methods as detailed below. To ensure effective camera movements, it is recommended not to combine more than 3 instructions.
1. Supports 15 camera movement methods (enumerated values):
(1) Lateral movements: [Pan Left], [Pan Right]
(2) Tilt movements: [Tilt Left], [Tilt Right]
(3) Push/Pull: [Push In], [Pull Out]
(4) Ascend/Descend: [Ascend], [Descend]
(5) Vertical tilting: [Tilt Up], [Tilt Down]
(6) Zoom: [Zoom In], [Zoom Out]
(7) Shake: [Shake]
(8) Follow: [Follow]
(9) Fixed: [Fixed]
2. Supports single and combined camera movements:
(1) Single movement: e.g., [Tilt Left], indicating a single camera action.
(2) Simultaneous multiple movements: Movements within the same group indicate simultaneous effects, e.g., [Tilt Left, Pan Right], signifying two combined camera actions that occur simultaneously.
(3) Sequential multiple movements: The instruction inserted first takes effect first. For example, in a prompt describing “xxx[Tilt Left], xxx[Pan Right]”, it indicates the video will first apply the tilt left movement, followed by the pan right movement.
II. Supports camera control through natural language description; using movement names in instructions enhances response accuracy.
III. Camera instructions and natural language descriptions can be effective simultaneously.
promptOptimizer promptOptimizer No The default value is true, prompting the model to automatically optimize the input to enhance generation quality. For more precise control, you can set this parameter to false, causing the model to adhere more strictly to instructions. In this case, it is recommended to provide a more detailed prompt to achieve the best results.
firstFrameImage string Yes The model will generate a video using the image provided in this parameter as the initial frame. It supports images in the data:image/jpeg;base64,{data} format as a Base64 encoded string, or via a publicly accessible URL. When using this parameter, the prompt can be set as an empty string or omitted altogether, allowing the model to autonomously determine how the scene evolves.
The uploaded image must meet the following criteria:
1. Format: JPG/JPEG/PNG.
2. Aspect ratio greater than 2:5 and less than 5:2.
3. Shortest side must be more than 300px.
4. Size must not exceed 20MB.

Response

Parameter Type Description
taskId string TaskID

Example

Request

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"
}'

Response

{
    "taskId": "1896852590888419329"
}

MaaS_HL_Video_t2v_director （text to video director）

Request method

POST

Request path

{basePath}/{endpointPath}/hailuo/video/generate

Request header

Parameter Description Example
Authorization AccessKey
Bearer ${AccessKey}		 Bearer RWXXXXXXX0Gd

Request body

Parameter Type Required Description
prompt string Yes Description for generating video. (Note: Maximum support of 2000 characters).
I. Supports insertion of camera movement instructions for camera control: Camera movement instructions should be inserted into the prompt in the [ ] format at the point of camera application. The standard format is [C1,C2,C3], where C represents different types of camera movements, supporting 15 enumerated methods as detailed below. To ensure effective camera movements, it is recommended not to combine more than 3 instructions.
1. Supports 15 camera movement methods (enumerated values):
(1) Lateral movements: [Pan Left], [Pan Right]
(2) Tilt movements: [Tilt Left], [Tilt Right]
(3) Push/Pull: [Push In], [Pull Out]
(4) Ascend/Descend: [Ascend], [Descend]
(5) Vertical tilting: [Tilt Up], [Tilt Down]
(6) Zoom: [Zoom In], [Zoom Out]
(7) Shake: [Shake]
(8) Follow: [Follow]
(9) Fixed: [Fixed]
2. Supports single and combined camera movements:
(1) Single movement: e.g., [Tilt Left], indicating a single camera action.
(2) Simultaneous multiple movements: Movements within the same group indicate simultaneous effects, e.g., [Tilt Left, Pan Right], signifying two combined camera actions that occur simultaneously.
(3) Sequential multiple movements: The instruction inserted first takes effect first. For example, in a prompt describing “xxx[Tilt Left], xxx[Pan Right]”, it indicates the video will first apply the tilt left movement, followed by the pan right movement.
II. Supports camera control through natural language description; using movement names in instructions enhances response accuracy.
III. Camera instructions and natural language descriptions can be effective simultaneously.
promptOptimizer promptOptimizer No The default value is true, prompting the model to automatically optimize the input to enhance generation quality. For more precise control, you can set this parameter to false, causing the model to adhere more strictly to instructions. In this case, it is recommended to provide a more detailed prompt to achieve the best results.
firstFrameImage string No The model will generate a video using the image provided in this parameter as the initial frame. It supports images in the data:image/jpeg;base64,{data} format as a Base64 encoded string, or via a publicly accessible URL. When using this parameter, the prompt can be set as an empty string or omitted altogether, allowing the model to autonomously determine how the scene evolves.
The uploaded image must meet the following criteria:
1. Format: JPG/JPEG/PNG.
2. Aspect ratio greater than 2:5 and less than 5:2.
3. Shortest side must be more than 300px.
4. Size must not exceed 20MB.

Response

Parameter Type Description
taskId string TaskID

Example

Request

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": "  "
}'

Response

{
    "taskId": "1896852590888419329"
}

MaaS_HL_Video_s2v（subject to video）

Request method

POST

Request path

{basePath}/{endpointPath}/hailuo/video/generate

Request header

Parameter Description Example
Authorization AccessKey
Bearer ${AccessKey}		 Bearer RWXXXXXXX0Gd

Request body

Parameter Type Required Description
prompt string No Description of the Generated Video: (Note: Maximum supported length is 2000 characters.)
promptOptimizer promptOptimizer No The default value is set to true, allowing the model to automatically optimize the input prompt to enhance generation quality. For more precise control, you can set this parameter to false, prompting the model to adhere strictly to instructions. In this case, it is recommended to provide a more detailed prompt to achieve the best results.
firstFrameImage string No The model will use the image provided in this parameter as the initial frame for generating the video. It supports images in the format of a Base64 encoded string, such as data:image/jpeg;base64,{data}, or a publicly accessible URL. When this parameter is used, the prompt can be left as an empty string or omitted, allowing the model to independently determine the evolution of the frames.
The image must meet the following conditions:
1. Format: JPG/JPEG/PNG
2. Aspect ratio between 2:5 and 5:2
3. Short side with more than 300px
4. Size not exceeding 20MB.
type string Yes Subject type, currently only "character" is supported, meaning a human facial subject.
image string Yes The reference image for the subject should be stored as a string in an array using the data:image/jpeg;base64,{data} format as a Base64 encoded string, or a publicly accessible URL. Currently, the array length is limited to 1, supporting only a single reference image.
The reference image must be less than 20MB in size, with formats supported being jpg, jpeg, and png.
Note: The image must contain valid subject information; otherwise, the video generation process will fail (though task creation will not be hindered). In such cases, the query interface will return a failed status for the video generation task.

Response

Parameter Type Description
taskId string TaskID

Example

Request

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"
            ]
        }
    ]
}'

Response

{
    "taskId": "1896852590888419329"
}

Retrieve the fileId.

Request method

GET

Request path

{basePath}/{endpointPath}/hailuo/video/task/{taskId}

Request header

Parameter Description Example
Authorization AccessKey
Bearer ${AccessKey}		 Bearer RWXXXXXXX0Gd

Response

Parameter Type Description
taskId string The task ID being queried this time.
status string Task status, including the following states: Preparing, Queueing, Processing, Success, Fail.
fileId string Upon successful completion of the task, this field returns the file ID corresponding to the generated video.
videoWidth Integer Upon successful completion of the task, this field will return the number of horizontal pixels of the generated video.
videoHeight Integer Upon successful completion of the task, this field will return the number of vertical pixels of the generated video.

Example

Request

curl --location --request GET 'https://genaiapi.cloudsway.net/v1/ai/xxxxxxxxxx/hailuo/video/task/{taskID}' \
--header 'Authorization: Bearer {YOUR_ACCESS_KEY}'

Response

{
    "status": "Preparing",
    "file_id": "",
    "task_id": "244785605570723",
    "base_resp": {
        "status_msg": "success",
        "status_code": 0
    },
    "video_width": 0,
    "video_height": 0
}

Retrieve the video URL.

Request method

GET

Request path

{basePath}/{endpointPath}/hailuo/video/file?taskId={taskID}&fileId={fileID}

Request header

Parameter Description Example
Authorization AccessKey
Bearer ${AccessKey}		 Bearer RWXXXXXXX0Gd

Response

Parameter Type Description
taskId string The task ID being queried this time.
createdAt string The Unix timestamp, in seconds, at the time of file creation.
filename string The name of the file.
purpose Integer The intended purpose of the file.
mediaUrl Integer video url
expireTime string The expiration time of the file, measured in seconds.

Example

Request

curl --location --request GET 'https://genaiapi.cloudsway.net/v1/ai/xxxxxx/hailuo/video/file?taskId={taskID}&fileId={fileID}' \
--header 'authorization: Bearer {YOUR_ACCESS_KEY}'

Response

{
    "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
}