HappyHorse reference-to-video API reference-Alibaba Cloud Model Studio(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.

NoteThe sample code in this topic applies to the China (Beijing) region.

ImportantAlibaba 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 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

China (Beijing)

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

Singapore

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

US (Virginia)

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

Germany (Frankfurt)

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

Japan (Tokyo)

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

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

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.

ImportantIf 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. For available models, see the Model Studio console.

Example: happyhorse-1.1-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:

480P
720P
1080P: Default value.

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.

Reference-to-video (multi-image)

# The URL below is for the China (Beijing) region. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
curl --location 'https://{WorkspaceId}.cn-beijing.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
    }
}'

Response parameters

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.

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": "Invalid API-key provided.",
    "request_id": "7438d53d-6eb8-4596-8835-xxxxxx"
}

Step 2: Get the task result

China (Beijing)

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

Singapore

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

US (Virginia)

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

Germany (Frankfurt)

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

Japan (Tokyo)

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

China (Hong Kong)

GET https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/api/v1/tasks/{task_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.
RPS limit: The default RPS for the query API is 20. For higher-frequency queries or event notifications, we recommend that you configure asynchronous task callbacks.
More operations: For batch queries, task cancellations, and other operations, see Manage asynchronous tasks.

Request parameters

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.

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}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

Response parameters

outputobject

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. format is YYYY-MM-DD HH:mm:ss.SSS.

scheduled_time string

The time when the task was executed. format is YYYY-MM-DD HH:mm:ss.SSS.

end_time string

The time when the task was completed. 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.

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

Error codes

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