HappyHorse - image-to-video-first frame API reference

The HappyHorse image-to-video model generates physically realistic and smooth-motion videos from a first frame and a text prompt.

Usage notes

The model, endpoint URL, and API key must belong to the same region. Cross-region calls fail.

Select a model: Check which region the model belongs to.
Select a URL: Select the endpoint URL for the same region.
Configure an API key : Get an API key for the same region, and then configure the API key as an environment variable.

Note

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

HTTP calls

Image-to-video tasks typically take 1--5 minutes, so the API uses asynchronous calls: "Create a task → poll for the result".

Step 1: Create a task

Singapore

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

US (Virginia)

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

China (Beijing)

POST https://dashscope.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

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 Postman.

Request parameters

## Image-to-video

curl

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-i2v",
 "input": {
 "prompt": "A cat running on the grass",
 "media": \[
 {
 "type": "first_frame",
 "url": "https://cdn.translate.alibaba.com/r/wanx-demo-1.png"
 }
 \]
 },
 "parameters": {
 "resolution": "720P",
 "duration": 5
 }
}'

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. Allowed value:

happyhorse-1.0-i2v

input *object* (required) Input data for the model, such as the text prompt. Properties

prompt *string* (optional) Describes the video content to generate. Any language is supported. Maximum length: 5,000 non-Chinese characters or 2,500 Chinese characters. Longer input is truncated.

media *array* (required) An array that specifies the input image. media[] element properties

type *string* (required) The type of media. Allowed value:

first_frame: The first frame. Constraint: You must provide exactly one first frame image.

url *string* (required) The URL of the media. Input image (type=first_frame) The URL or Base64-encoded data of the first frame image. Image constraints:

Formats: JPEG, JPG, PNG, WEBP.
Resolution: Width and height must both be at least 300 pixels.
Aspect ratio: Between 1:2.5 and 2.5:1.
File size: Up to 20 MB. Supported input formats:
Public URL: <li> HTTP and HTTPS are supported.
Example: https://xxx/xxx.png. </li>
Base64-encoded image string: <li> Format: data:{MIME_type};base64,{base64_data}.
Example: data:image/png;base64,GDU7MtCZzEbTbmRZ...... (truncated for display). Base64 encoding format Format: data:{MIME_type};base64,{base64_data} . <li> {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

</li> </li>

parameters *object* (optional) Video generation parameters, such as resolution and duration. Properties

resolution *string* (optional) The resolution of the generated video. The model scales the output to a pixel count close to the selected tier while maintaining the aspect ratio of the input first frame. Allowed values:

720P
1080P (Default)

duration *integer* (optional) The duration of the generated video, in seconds. The value must be an integer in the range [3, 15]. Default: 5.

watermark *boolean* (optional) Whether to add a watermark to the video. If true, the text "Happy Horse" is added to the bottom-right corner.

true (Default)
false

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.

json

{
 "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 messages.

json

{
 "code": "InvalidApiKey",
 "message": "No API-key provided.",
 "request_id": "7438d53d-6eb8-4596-8835-xxxxxx"
}

     **output** `*object*` The task's output.

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 messages.

message *string* Detailed error message. Returned only for failed requests. See Error messages.

Step 2: Poll for the result

Singapore

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

US (Virginia)

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

China (Beijing)

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

Germany (Frankfurt)

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

Replace WorkspaceId with your actual Workspace ID. Note

Polling recommendation: Video generation takes several minutes. Use a polling mechanism with a reasonable interval, such as 15 seconds.
Task state transition: PENDING → RUNNING → SUCCEEDED or FAILED.
Result link : After a task succeeds, a video URL valid for 24 hours is returned. Download and save the video to permanent storage, such as OSS.
task_id****validity : 24 hours . After this period, queries return the task status as 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

curl -X GET https://dashscope-intl.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.

Path parameters

task_id *string* (Required) The ID of the task.

Response parameters

## Task successful

Video URLs are valid for only 24 hours and then automatically purged. Save generated videos promptly.

json

{
 "request_id": "8ae698ba-df2d-966c-abcf-xxxxxx",
 "output": {
 "task_id": "e56d806f-76f9-4037-aefa-xxxxxx",
 "task_status": "SUCCEEDED",
 "submit_time": "2026-04-20 19:33:50.425",
 "scheduled_time": "2026-04-20 19:33:50.463",
 "end_time": "2026-04-20 19:35:34.216",
 "orig_prompt": "A cat running on the grass",
 "video_url": "https://dashscope-result.oss-cn-beijing.aliyuncs.com/xxx.mp4?Expires=xxx"
 },
 "usage": {
 "duration": 5,
 "input_video_duration": 0,
 "output_video_duration": 5,
 "video_count": 1,
 "SR": 720
 }
}

## Task failed

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

json

{
 "request_id": "e5d70b02-ebd3-98ce-9fe8-759d7d7b107d",
 "output": {
 "task_id": "86ecf553-d340-4e21-af6e-a0c6a421c010",
 "task_status": "FAILED",
 "code": "InvalidParameter",
 "message": "The parameter is invalid."
 }
}

## Task query expired

The task_id is valid for 24 hours. After this period, queries return the following error.

json

{
 "request_id": "a4de7c32-7057-9f82-8581-xxxxxx",
 "output": {
 "task_id": "502a00b1-19d9-4839-a82f-xxxxxx",
 "task_status": "UNKNOWN"
 }
}

     **output **`*object*` The task's output.

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* Returned only when task_status is SUCCEEDED. The URL is valid for 24 hours. Download the MP4 video (24 fps, H.264 encoded) from this URL.

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, calculated only for successful tasks.

Properties

input_video_duration *integer* The duration of the input video, in seconds.

output_video_duration *integer* The duration of the output video, in seconds.

duration *integer* The total video duration used for billing.

SR *integer* The resolution of the output video.

video_count *integer* The number of output videos. This value is always 1.

request_id *string* Unique request identifier for tracing and troubleshooting.

Error codes

If a call fails, see error messages for troubleshooting.

FAQ

Video aspect ratio

The output video automatically matches the first frame's aspect ratio. Unlike the HappyHorse text-to-video model, the image-to-video model does not support the ratio parameter.

HappyHorse - image-to-video-first frame API reference ​

Usage notes ​

HTTP calls ​

Step 1: Create a task ​

Singapore ​

US (Virginia) ​

China (Beijing) ​

Germany (Frankfurt) ​

Request parameters ​

## Image-to-video ​

Request body ​

Response parameters ​

Successful response ​

Error response ​

Step 2: Poll for the result ​

Singapore ​

US (Virginia) ​

China (Beijing) ​

Germany (Frankfurt) ​

Request parameters ​

## Query task result ​

Request headers ​

Path parameters ​

Response parameters ​

## Task successful ​

## Task failed ​

## Task query expired ​

Error codes ​

FAQ ​

Video aspect ratio ​

HappyHorse - image-to-video-first frame API reference

Usage notes

HTTP calls

Step 1: Create a task

Singapore

US (Virginia)

China (Beijing)

Germany (Frankfurt)

Request parameters

## Image-to-video

Request body

Response parameters

Successful response

Error response

Step 2: Poll for the result

Singapore

US (Virginia)

China (Beijing)

Germany (Frankfurt)

Request parameters

## Query task result

Request headers

Path parameters

Response parameters

## Task successful

## Task failed

## Task query expired

Error codes

FAQ

Video aspect ratio