Skip to content

Text-to-Video API

Version History

Version Date Changes
v1.0 2024-08-29 Initial release

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
}

MaaS Haiper Video

Common Information

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

According to the above example, the final request path for the Generate Video API is https://genaiapi.cloudsway.net/v1/ai/LPUqHEAjfonOmohV/video/generate

Generate Video

Request Method

POST

Request Path

{basePath}/{endpointPath}/video/generate

Request Headers

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

Request Body

Field Name Type Required Description Example Value
prompt String Yes Prompt for video generation "Generate a video of a sunset over the ocean."
negativePrompt String No Negative prompt "Avoid dark and gloomy scenes."
config Object No Configuration options
- sourceImage URI No Public URL of the source image, supports http and https "https://demo.jpg"
settings Object No Settings
- seed Number No Default is -1, random seed for sampling 42
- duration Number No Default is 2, duration of the output video, supports 2, 4, and 8 2
- aspectRatio String No Default is 16:9, valid values are (16:9, 9:16, 3:4, 4:3, 1:1) "16:9"

Response

Field Name Type Description Example Value
taskId String Unique identifier of the task "1234abcd"

Example

Request

curl -X POST "https://genaiapi.cloudsway.net/v1/ai/LPUqHEAjfonOmohV/video/generate" \
  -H "Authorization: Bearer RWxxxxxxxx0Gd" \
  -H "Content-Type: application/json" \
  -d '{
        "prompt": "Generate a video of a sunset over the ocean.",
        "negativePrompt": "Avoid dark and gloomy scenes.",
        "config": {
          "sourceImage": "https://demo.jpg"
        },
        "settings": {
          "seed": 42,
          "duration": 2,
          "aspectRatio": "16:9"
        }
      }'

Response

{
  "taskId": "1234abcd"
}

Upscale Video

Request Method

POST

Request Path

{basePath}/{endpointPath}/video/upscale

Request Headers

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

Request Body

Field Name Type Required Description Example Value
config Object Yes Configuration options
- sourceVideo URI Yes Public URL of the source video, supports http and https "https://demo.mp4"

Response

Field Name Type Description Example Value
taskId String Unique identifier of the task "1234abcd"

Example

Request

curl -X POST "https://genaiapi.cloudsway.net/v1/ai/LPUqHEAjfonOmohV/video/upscale" \
  -H "Authorization: Bearer RWxxxxxxxx0Gd" \
  -H "Content-Type: application/json" \
  -d '{
        "config": {
          "sourceVideo": "https://demo.mp4"
        }
      }'

Response

{
  "taskId": "1234abcd"
}

Extend Video

Request Method

POST

Request Path

{basePath}/{endpointPath}/video/extend

Request Headers

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

Request Body

Field Name Type Required Description Example Value
prompt String No Prompt for video generation "Generate a video of a sunset over the ocean."
negativePrompt String No Negative prompt "Avoid dark and gloomy scenes."
config Object Yes Configuration options
- sourceVideo URI Yes Public URL of the source video, supports http and https "https://demo.mp4"
- extendDuration Number No Default is 4, duration to extend the video, supports 2 and 4 seconds 4
settings Object No Settings
- seed Number No Default is -1, random seed for sampling 42
- guidanceScale Number No Default is 7.5, guidance scale setting 7.5

Response

Field Name Type Description Example Value
taskId String Unique identifier of the task "1234abcd"

Example

Request

curl -X POST "https://genaiapi.cloudsway.net/v1/ai/LPUqHEAjfonOmohV/video/extend" \
  -H "Authorization: Bearer RWxxxxxxxx0Gd" \
  -H "Content-Type: application/json" \
  -d '{
        "prompt": "Generate a video of a sunset over the ocean.",
        "negativePrompt": "Avoid dark and gloomy scenes.",
        "config": {
          "sourceVideo": "https://demo.mp4",
          "extendDuration": 4
        },
        "settings": {
          "seed": 42,
          "guidanceScale": 7.5
        }
      }'

Response

{
  "taskId": "1234abcd"
}

Query Video Task Result

Request Method

GET

Request Path

{basePath}/{endpointPath}/video/tasks/{taskId}

Request Headers

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

Path Variables

Field Name Type Description Example Value
taskId String Unique identifier of the task "1234abcd"

Response

Field Name Type Description Example Value
status String Task status, possible values: PENDING, IN_PROGRESS, SUCCESS, FAIL SUCCESS
mediaUrl String URL of the generated media file
expireTime Number Timestamp of the URL expiration time 1724241996259
progress Number Progress, 1 means completed 0.85

Example

Request

curl -X GET "https://genaiapi.cloudsway.net/v1/ai/LPUqHEAjfonOmohV/video/tasks/1234abcd" \
  -H "Authorization: Bearer RWxxxxxxxx0Gd"

Response

{
  "status": "SUCCESS",
  "mediaUrl": "https://generated-video-url.mp4",
  "expireTime": 1724241996259,
  "progress": 0.85
}