HappyHorse video editing API reference - Alibaba Cloud Model Studio

Availability

Make sure that the model, endpoint URL, and API key all belong to the same region. Cross-region calls will fail.

Select a model: Check which region the model belongs to.
Select a URL: Use the endpoint URL for the corresponding region. HTTP URLs are supported.
Configure an API key: Select a region and Create an API key, then Export API key as environment variable.

The sample code in this topic applies to the Singapore region.

Alibaba Cloud Model Studio has released workspace-specific domains for the China (Beijing) and Singapore regions. The new dedicated domains deliver superior performance and higher stability for inference requests. We recommend migrating to the new domains:

China (Beijing): from https://dashscope.aliyuncs.com to https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
Singapore: from https://dashscope-intl.aliyuncs.com to https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

{WorkspaceId} is your workspace ID, which can be found on the Workspace Details page in the Alibaba Cloud Model Studio console. The existing domain remains fully functional.

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
US (Virginia)
China (Beijing)
Germany (Frankfurt)
Japan (Tokyo)

POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

Replace {WorkspaceId} with your actual workspace ID.

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 Call APIs with Postman or cURL.

Request parameters

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.

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 any language. Maximum 5,000 non-Chinese characters or 2,500 Chinese 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:

video: Required. The video to edit.
reference_image: Optional. A reference image.

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.

Supports HTTP and HTTPS.
Example: https://xxx/xxx.mp4.

Video requirements:

Format: MP4, MOV (H.264 encoding recommended).
Duration: 3–60 seconds.
Resolution: the longer side must not exceed 4,096 px; the shorter side must be at least 360 px.
Aspect ratio: 1:2.5–2.5:1.
File size: up to 100 MB.
Frame rate: 8-60 fps. If the input video has a variable frame rate, ensure that the frame rate changes remain within this range.

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)

URL or Base64-encoded data of the reference image.Image requirements:

Format: JPEG, JPG, PNG, WEBP.
Resolution: both width and height must be at least 300 px.
Aspect ratio: 1:2.5–2.5:1.
File size: up to 20 MB.

Supported input formats:

Public URL:
- Supports HTTP and HTTPS.
- Example: https://xxx/xxx.png.
Base64-encoded image string:
- Format: data:{MIME_type};base64,{base64_data}.
- Example: data:image/png;base64,GDU7MtCZzEbTbmRZ...... (truncated for demonstration).
  Base64 encoding data format
  Format: data:{MIME_type};base64,{base64_data} .
  - {base64_data}: The Base64-encoded string of the image file.
  - {MIME_type}: The media type of the image, which must match the file format.
  Image format
  MIME Type
  JPEG
  image/jpeg
  JPG
  image/jpeg
  PNG
  image/png
  WEBP
  image/webp

parameters object (Optional)Video editing parameters such as resolution.

Properties

resolution string (Optional)Resolution of the generated video.Valid values:

1080P (default)
720P

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.

true (default)
false

audio_setting string (Optional)Audio control.

auto (default): Determined by the model.
origin: Preserves the original audio from the input video.

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.

Video editing (instruction + reference image)

# The following URL is for the Singapore region. When calling, replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.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"
    }
}'

Response parameters

output objectThe task output information.

Properties

task_id stringThe task ID. Valid for queries for 24 hours.task_status stringThe status of the task.

Enumeration values

PENDING
RUNNING
SUCCEEDED
FAILED
CANCELED
UNKNOWN: The task does not exist or its status is unknown.

request_id stringUnique request identifier for tracing and troubleshooting.code stringError code. Returned only for failed requests. See Error codes.message stringDetailed error message. Returned only for failed requests. See Error codes.

Successful response
Error response

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

Step 2: Query results by task ID

Singapore
US (Virginia)
China (Beijing)
Germany (Frankfurt)
Japan (Tokyo)

GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}

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

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.

Query 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, Replace {WorkspaceId} with your actual workspace ID.

curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

Response parameters

outputobjectTask output information.

Properties

task_id stringThe task ID. Valid for queries for 24 hours.task_status stringThe status of the task.

Enumeration values

PENDING
RUNNING
SUCCEEDED
FAILED
CANCELED
UNKNOWN: The task does not exist or its status is unknown.

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 stringThe 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 stringThe 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 stringThe 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 stringURL 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 stringThe original input prompt, corresponding to the request parameter prompt.code stringError code. Returned only for failed requests. See Error codes.message stringDetailed error message. Returned only for failed requests. See Error codes.

usage objectUsage statistics. Only counts successful results.

Properties

duration floatTotal video duration of the generated video, used for billing.SR integerResolution tier of the generated video.output_video_duration floatDuration of the output video, in seconds.input_video_duration floatDuration of the input video, in seconds.video_count integerNumber of generated videos. Always 1.

request_id stringUnique request identifier for tracing and troubleshooting.

Task succeeded
Task failed
Task query expired

Video 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
    }
}

When a task fails, task_status is FAILED with an error code and message. See Error codes.

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

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

Error codes

If the model call fails and returns an error message, see Error codes for resolution.

​Availability

​HTTP request

​Step 1: Create a task and get the task ID

Request parameters

Headers

Request body

Response parameters

​Step 2: Query results by task ID

Request parameters

Headers

Path parameters

Response parameters

​Error codes

Availability

HTTP request

Step 1: Create a task and get the task ID

Step 2: Query results by task ID

Error codes