The HappyHorse video editing model takes a video and a reference image as input, and performs editing tasks such as style transfer and local replacement based on text instructions.
Availability
Make sure that the model, endpoint URL, and API key all belong to the same region. Cross-region calls will fail.
Note The sample code in this topic applies to the Singapore region.
HTTP request
Video editing tasks are time-consuming (typically 1–5 minutes), so the API uses asynchronous calls. The workflow has two steps: "Create a task -> Poll for result" as described below:
Step 1: Create a task and get the task ID
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 | Video editing (instruction + reference 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-video-edit",
"input": {
"prompt": "Make the horse-headed humanoid character in the video wear the striped sweater from the image",
"media": [
{
"type": "video",
"url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260409/dozxak/Wan_Video_Edit_33_1.mp4"
},
{
"type": "reference_image",
"url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260415/hynnff/wan-video-edit-clothes.webp"
}
]
},
"parameters": {
"resolution": "720P"
}
}'
|
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) The model name. Fixed value: happyhorse-1.0-video-edit. |
input object (Required) The input information, including the video to edit, reference images, and the prompt. Properties prompt string (Required) The text prompt describing the intended edit, such as style transfer or local replacement. Supports Chinese and English. Each Chinese character or letter counts as one character. Maximum 2,500 characters; content beyond this limit is automatically truncated. media array (Required) The list of media assets, including the video to edit and optional reference images. The array must contain exactly 1 video element and can optionally contain 0–5 reference_image elements. Element properties type string (Required) The media asset type. Must be one of: Asset limits: Videos: exactly 1. Reference images: 0–5.
url string (Required) The URL of the media asset. Video input (type=video) A publicly accessible URL of the video to edit. Video requirements: Format: MP4, MOV (H.264 encoding recommended). Duration: 3–60 seconds. Resolution: the shorter side must be at least 360 px. Aspect ratio: 1:8–8:1. File size: up to 100 MB. Frame rate: greater than 8 fps.
Note Output video duration: 3–15 seconds. If the input video is 15 seconds or shorter, the output video has the same duration as the input. If the input video is longer than 15 seconds, the system automatically uses only the first 15 seconds, so the maximum output duration is 15 seconds.
Image input (type=reference_image) A publicly accessible URL of the reference image. Image requirements: Format: JPEG, JPG, PNG, BMP, WEBP. Resolution: both width and height must be at least 300 px. Aspect ratio: 1:2.5–2.5:1. File size: up to 10 MB.
|
parameters object (Optional) Video editing parameters such as resolution. Properties resolution string (Optional) Resolution of the generated video. Valid values: watermark boolean (Optional) Whether to add a watermark to the generated video. The watermark appears in the bottom-right corner with the text "Happy Horse". Defaults to true. 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 The task output information. 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: Query 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 editing 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 expiration: The task_id expires after 24 hours. After expiration, results can no longer be retrieved and the API returns a task status of UNKNOWN.
Request parameters | Query task resultReplace {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 succeededVideo URLs are valid for only 24 hours and then automatically purged. Save generated videos promptly. {
"request_id": "c11018a8-3f83-9591-a636-xxxxxx",
"output": {
"task_id": "051c7b40-b2c5-4341-aee4-xxxxxx",
"task_status": "SUCCEEDED",
"submit_time": "2026-04-26 14:13:14.373",
"scheduled_time": "2026-04-26 14:13:14.419",
"end_time": "2026-04-26 14:14:13.679",
"orig_prompt": "Dress the horse-headed humanoid character in the video in the striped sweater from the image",
"video_url": "https://dashscope-result.oss-cn-beijing.aliyuncs.com/xxxx.mp4"
},
"usage": {
"duration": 13.24,
"input_video_duration": 6.62,
"output_video_duration": 6.62,
"video_count": 1,
"SR": "720"
}
}
Task failedWhen 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 query expiredThe 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 information. 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 successful results. Properties duration float Total video duration of the generated video, used for billing. SR integer Resolution tier of the generated video. output_video_duration float Duration of the output video, in seconds. input_video_duration float Duration of the input video, in seconds. 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.