Availability
Make sure the model, endpoint URL, and API key all belong to the same region. Cross-region calls will fail.
Note
The sample code applies to the Singapore region.
HTTP
Reference-to-video tasks take 1–5 minutes to complete. The API uses asynchronous calls with two steps: "Create a task -> Poll for results".
Step 1: Create a task
Singapore
POST https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis
Beijing
POST https://dashscope.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis
Note After the task is created, use the returned task_id to query the result. The task_id is valid for 24 hours. Do not create duplicate tasks. Instead, use polling to retrieve the result.
For guidance for beginners, see Postman.
Request parameters
|
Reference-to-video (multi-image)curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
-H 'X-DashScope-Async: enable' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "happyhorse-1.0-r2v",
"input": {
"prompt": "身着红色旗袍的女性character1，镜头先以侧面中景勾勒旗袍修身剪裁与S型曲线，随即切换至低角度仰拍，捕捉她轻抬玉手展开折扇character2时流苏耳坠character3随头部转动轻盈摆动的细节，最后推近至面部特写，定格在她指尖轻点扇骨、眼波流转间的含蓄风情，多视角全方位展现东方韵味。",
"media": [
{
"type": "reference_image",
"url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260424/mvzfud/hh-v2v-girl.jpg"
},
{
"type": "reference_image",
"url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260424/fvuihk/hh-v2v2-folding-fan.jpg"
},
{
"type": "reference_image",
"url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260424/imerii/hh-v2v-earrings.jpg"
}
]
},
"parameters": {
"resolution": "720P",
"ratio": "16:9",
"duration": 5
}
}'
|
Headers
|
|
Content-Type string (Required) The content type of the request. Must be application/json.
|
|
Authorization string (Required) Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.
|
|
X-DashScope-Async string (Required) Enables asynchronous processing. HTTP requests support only asynchronous calls. Must be enable.
Important If this request header is missing, the error "current user api does not support synchronous calls" is returned. |
Request body
|
|
model string (Required)
Model name.
Fixed value: happyhorse-1.0-r2v.
|
|
input object (Required)
Input content, including reference images and the text prompt.
Properties
prompt string (Required)
Text prompt describing the desired elements and visual style of the generated video.
Supports Chinese and English. Each character (Chinese character or letter) counts as one character in UTF-8 encoding. Maximum 2,500 characters; content beyond this limit is automatically truncated.
Reference citation: Use "character1", "character2" in the prompt to reference the corresponding image in the media array. The order matches the media array order.
media array (Required)
List of media assets for reference images.
Each element is a media object containing a type and url field.
The array order defines the character reference order in the prompt. The first reference_image maps to character1, the second to character2, and so on.
Element properties
type string (Required)
Media asset type. Fixed value:
Asset limits:
url string (Required)
Publicly accessible URL of the image file.
Image limits:
-
Format: JPEG, JPG, PNG, BMP, and WEBP.
-
Resolution: shortest side at least 400 px. 720P or higher recommended. Avoid small, blurry, or heavily compressed images, as they degrade output quality.
-
File size: 10 MB maximum.
|
|
parameters object (Optional)
Video generation parameters such as resolution, aspect ratio, and duration.
Properties
resolution string (Optional)
Resolution of the generated video.
Valid values:
ratio string (Optional)
Aspect ratio of the generated video.
Valid values:
-
16:9: Default.
-
9:16
-
3:4
-
4:3
-
1:1
duration integer (Optional)
Duration of the generated video, in seconds.
Must be an integer between 3 and 15.
Defaults to 5.
watermark boolean (Optional)
Whether to add a watermark to the generated video. The watermark appears in the bottom-right corner with fixed text "Happy Horse".
seed integer (Optional) The random number seed must be an integer in the range [0, 2147483647]. If not specified, a random seed is generated. A fixed seed improves reproducibility. Because model generation is probabilistic, the same seed does not guarantee identical results.
|
Response parameters
|
Successful responseSave the task_id to query the task status and result. {
"output": {
"task_status": "PENDING",
"task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
},
"request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}
Error responseTask creation failed. See Error messages. {
"code": "InvalidApiKey",
"message": "No API-key provided.",
"request_id": "7438d53d-6eb8-4596-8835-xxxxxx"
}
|
|
output object
Task output.
Properties
task_id string The task ID. Valid for queries for 24 hours.
task_status string The status of the task.
|
|
request_id string Unique request identifier for tracing and troubleshooting.
|
|
code string Error code. Returned only for failed requests. See Error messages.
|
|
|
message string Detailed error message. Returned only for failed requests. See Error messages.
|
|
Step 2: Retrieve results by task ID
Singapore
GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/{task_id}
Beijing
GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}
Note
-
Polling: Video generation takes several minutes. Use a polling mechanism with a reasonable interval (for example, 15 seconds) to check for results.
-
Task status flow: PENDING (queued) → RUNNING (processing) → SUCCEEDED / FAILED.
-
task_id validity: 24 hours. After expiration, results can no longer be retrieved, and the API returns a task status of UNKNOWN.
Request parameters
|
Retrieve task result
Replace {task_id} with the task_id value returned by the previous API call. The task_id is valid for queries for 24 hours. curl -X GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
|
Headers
|
|
Authorization string (Required) Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.
|
Path parameters
|
|
task_id string (Required) The ID of the task.
|
Response parameters
|
Task succeeded
Video URLs are valid for only 24 hours and then automatically purged. Save generated videos promptly. {
"request_id": "35137489-2862-96cb-b6f2-xxxxxx",
"output": {
"task_id": "1469cfc3-3004-4d9e-ab10-xxxxxx",
"task_status": "SUCCEEDED",
"submit_time": "2026-04-25 15:03:25.848",
"scheduled_time": "2026-04-25 15:03:25.884",
"end_time": "2026-04-25 15:04:05.882",
"orig_prompt": "身着红色旗袍的女性character1，镜头先以侧面中景勾勒旗袍修身剪裁与S型曲线，随即切换至低角度仰拍，捕捉她轻抬玉手展开折扇character2时流苏耳坠character3随头部转动轻盈摆动的细节，最后推近至面部特写，定格在她指尖轻点扇骨、眼波流转间的含蓄风情，多视角全方位展现东方韵味。",
"video_url": "https://dashscope-result.oss-cn-beijing.aliyuncs.com/xxxx.mp4"
},
"usage": {
"duration": 5,
"input_video_duration": 0,
"output_video_duration": 5,
"video_count": 1,
"SR": 720,
"ratio": "16:9"
}
}
Task failed
When a task fails, task_status is FAILED with an error code and message. See Error messages. {
"request_id": "e5d70b02-ebd3-98ce-9fe8-759d7d7b107d",
"output": {
"task_id": "86ecf553-d340-4e21-af6e-a0c6a421c010",
"task_status": "FAILED",
"code": "InvalidParameter",
"message": "The resolution is not valid xxxxxx"
}
}
Task expired
The task_id is valid for 24 hours. After this period, queries return the following error. {
"request_id": "a4de7c32-7057-9f82-8581-xxxxxx",
"output": {
"task_id": "502a00b1-19d9-4839-a82f-xxxxxx",
"task_status": "UNKNOWN"
}
}
|
|
output object
Task output.
Properties
task_id string The task ID. Valid for queries for 24 hours.
task_status string The status of the task. State transitions during polling: PENDING → RUNNING → SUCCEEDED or FAILED. The initial query status is usually PENDING or RUNNING. When the status changes to SUCCEEDED, the response contains the generated video URL. If the status is FAILED, check the error message and retry the task.
submit_time string The time when the task was submitted. The time is in UTC+8 and the format is YYYY-MM-DD HH:mm:ss.SSS.
scheduled_time string The time when the task was executed. The time is in UTC+8 and the format is YYYY-MM-DD HH:mm:ss.SSS.
end_time string The time when the task was completed. The time is in UTC+8 and the format is YYYY-MM-DD HH:mm:ss.SSS.
video_url string URL of the generated video. Returned only when task_status is SUCCEEDED. Valid for 24 hours. The video is in MP4 format with H.264 encoding.
orig_prompt string The original input prompt, corresponding to the request parameter prompt.
code string Error code. Returned only for failed requests. See Error messages.
message string Detailed error message. Returned only for failed requests. See Error messages.
|
|
usage object
Usage statistics. Only counts results from completed tasks.
Properties
duration integer
Total duration of the generated video, used for billing.
SR integer
Resolution tier of the generated video.
input_video_duration integer
Total duration of the input video, in seconds. Always 0 for reference-to-video.
output_video_duration integer
Total duration of the output video, in seconds.
ratio string
Aspect ratio of the generated video.
video_count integer
Number of generated videos. Always 1.
|
|
|
request_id string Unique request identifier for tracing and troubleshooting.
|
|
Error codes
If the model call fails and returns an error message, see Error messages for resolution.