HappyHorse reference-to-video API reference - Alibaba Cloud Model Studio

The HappyHorse reference-to-video model lets you provide multiple reference images and a text prompt to generate a video that combines subjects from the images into a scene based on the prompt.

Usage notes

To ensure successful API calls, you must use a model, endpoint URL, and API key that all belong to the same region. Cross-region calls will fail.

Select a model: Confirm the region where your model is located.
Select a URL: Choose the corresponding endpoint URL. Both HTTP and DashScope SDK URLs are supported.
Configure an API key: Select a region, get an API key, and then configure the API key as an environment variable.

Note

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

Important

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 Model Studio console. The existing domain remains fully functional.

HTTP calls

Because reference-to-video tasks are time-consuming (typically 1–5 minutes), the API uses an asynchronous call. The workflow consists of two core steps: "Create a task -> Poll for the result".

Step 1: Create a task

Singapore

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

Replace WorkspaceId with your actual Workspace ID.

US (Virginia)

POST https://dashscope-us.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

China (Beijing)

POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

Replace WorkspaceId with your actual Workspace ID.

Germany (Frankfurt)

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

Replace WorkspaceId with your Workspace ID.

China (Hong Kong)

POST https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

Replace WorkspaceId with your actual Workspace ID.

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

Request parameters

Reference-to-video (multi-image)

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.1-r2v",
    "input": {
        "prompt": "A woman in a red qipao from [Image 1] is first shown in a profile medium shot, highlighting the tailored cut and S-curve of the dress. The camera then switches to a low-angle shot, capturing her unfolding the fan from [Image 2] while the tassel earrings from [Image 3] sway with her head movement. The scene ends with a close-up of her face, focusing on the charm in her eyes as her fingertips touch the fan, showcasing Eastern elegance from multiple angles.",
        "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
    }
}'

Request 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 name of the model.

Valid values:

happyhorse-1.1-r2v
happyhorse-1.0-r2v

input object (Required)

The model input, which includes the reference images and text prompt.

Properties

prompt string (Required)

A description of the desired elements and visual style for the generated video.

Input in any language is supported. The length is limited to 5,000 non-Chinese characters or 2,500 Chinese characters. Content exceeding this limit is automatically truncated.

Image referencing: In the prompt, use "[Image 1]" and "[Image 2]" to refer to the corresponding reference image in the media array. The order must be consistent with the order in the media array. When using a reference, specify the object in the image, such as "the woman in a red qipao in [Image 1]".

media array (Required)

A list of reference images.

Each element in the array is a media object that contains type and url fields.

The order of elements in this array defines the order of subject references in the prompt.
The first reference_image in the array corresponds to [Image 1], the second to [Image 2], and so on.

Element properties

type string (Required)

The type of media asset. Set this to:

reference_image: A reference image.

Asset limits:

Number of reference images: 1 to 9.

url string (Required)

The URL or Base64-encoded data of a reference image.

Image requirements:

Formats: JPEG, JPG, PNG, WEBP.
Resolution: The shortest side must be at least 400 pixels. A clear image with a resolution of 720P or higher is recommended. Avoid using images that are too small, blurry, or overly compressed, as this can degrade the output quality.
Maximum file size: 20 MB.

Supported input formats:

Public URL:
- Supports HTTP or HTTPS protocols.
- Example: https://xxx/xxx.jpg.

Base64-encoded image string:

Data format: data:{MIME_type};base64,{base64_data}.

Example: data:image/png;base64,GDU7MtCZzEbTbmRZ...... (truncated for display purposes).

Base64-encoded 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)

Parameters for video generation, such as video resolution, aspect ratio, and duration.

Properties

resolution string (Optional)

The resolution tier of the generated video.

Valid values:

1080P: Default value.
720P

ratio string (Optional)

The aspect ratio of the generated video.

Valid values:

16:9: Default value.
9:16
3:4
4:3
4:5
5:4
1:1
9:21
21:9

duration integer (Optional)

The duration of the generated video, in seconds.

Value range: An integer from 3 to 15.

Default value: 5.

watermark boolean (Optional)

Specifies whether to add a watermark to the generated video. The watermark is placed in the bottom-right corner with the fixed text "Happy Horse".

true: Default value. A watermark is added.
false: No watermark is added.

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 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" }` Error response Task creation failed. See Error codes. `{ "code": "InvalidApiKey", "message": "No API-key provided.", "request_id": "7438d53d-6eb8-4596-8835-xxxxxx" }`
output `object` The output information for the task. Properties task_id `string` The task ID. Valid for queries for 24 hours. task_status `string` The status of the task. Enumeration values PENDING RUNNING SUCCEEDED FAILED CANCELED UNKNOWN: The task does not exist or its status is unknown.
request_id `string` Unique request identifier for tracing and troubleshooting.
code `string` Error code. Returned only for failed requests. See Error codes.
message `string` Detailed error message. Returned only for failed requests. See Error codes.

Step 2: Get the task result

Singapore

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

Replace WorkspaceId with your actual Workspace ID.

US (Virginia)

GET https://dashscope-us.aliyuncs.com/api/v1/tasks/{task_id}

China (Beijing)

GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}

Replace WorkspaceId with your actual Workspace ID.

Germany (Frankfurt)

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

Replace WorkspaceId with your Workspace ID.

China (Hong Kong)

GET https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/api/v1/tasks/{task_id}

Replace WorkspaceId with your actual Workspace ID.

Note

Polling recommendation: Video generation can take several minutes. We recommend that you implement a polling mechanism with a reasonable query interval (for example, 15 seconds) to retrieve the result.
Task status flow: PENDING (Queued) → RUNNING (Processing) → SUCCEEDED (Succeeded) or FAILED (Failed).
Task ID validity: The task ID is valid for 24 hours. After this period, you can no longer query the result, and the API returns a task status of UNKNOWN.

Request parameters	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. `curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id} \ --header "Authorization: Bearer $DASHSCOPE_API_KEY"`
Request headers
Authorization `string` (Required) Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.
URL 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": "A woman in a red qipao from [Image 1] is first shown in a profile medium shot, highlighting the dress'\''s tailored cut and S-curve. The camera then switches to a low-angle shot, capturing her unfolding the fan from [Image 2] while the tassel earrings from [Image 3] sway with her head movement. The scene ends with a close-up of her face, focusing on the charm in her eyes as her fingertips touch the fan, showcasing Eastern elegance from multiple angles.", "video_url": "https://dashscope-result-intl.oss-ap-southeast-1.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 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" } }` Task query 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` The output information for the task. Properties task_id `string` The task ID. Valid for queries for 24 hours. task_status `string` The 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 `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 codes. message `string` Detailed error message. Returned only for failed requests. See Error codes.
usage `object` Usage statistics for the task. You are only billed for successful tasks. Properties duration `integer` The billable duration of the generated video, in seconds. input_video_duration `integer` The total duration of the input video, in seconds. This is always 0 for reference-to-video tasks. output_video_duration `integer` The total duration of the output video, in seconds. ratio `string` The aspect ratio of the generated video. SR `integer` The resolution tier of the generated video. video_count `integer` The number of generated videos. This is 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 codes for resolution.

Usage notes

HTTP calls

Step 1: Create a task

Singapore

US (Virginia)

China (Beijing)

Germany (Frankfurt)

China (Hong Kong)

Request parameters

Reference-to-video (multi-image)

Request headers

Request body

Response parameters

Successful response

Error response

Step 2: Get the task result

Singapore

US (Virginia)

China (Beijing)

Germany (Frankfurt)

China (Hong Kong)

Request parameters

Query task result

Request headers

URL path parameters

Response parameters

Task succeeded

Task failed

Task query expired

Error codes