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

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.

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 calls

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

Step 1: Create a task

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

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. For available models, see the Model Studio console.Example: happyhorse-1.1-i2v.input object (required)Model input, including the text prompt.

Properties

prompt string (optional)Describes the video content to generate.Supports any language. Maximum: 5,000 non-Chinese characters or 2,500 Chinese characters. Longer input is truncated.media array (required)The input image array.

media[] element properties

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

first_frame: The first frame.

Exactly one first-frame image is required.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:
- HTTP and HTTPS are supported.
- Example: https://xxx/xxx.png.
Base64-encoded image string:
- 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} .
  - {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 output settings such as resolution and duration.

Properties

resolution string (optional)The resolution of the generated video.Output pixel count approximates the selected tier while preserving the input image's aspect ratio.Allowed values:

480P
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)Adds a "Happy Horse" text watermark 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.

Image-to-video

# The following URLs are for the Singapore region. Replace {WorkspaceId} with your Bailian 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.1-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
    }
}'

Response parameters

output objectThe task's output.

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: Poll for the result

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

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_idvalidity: 24 hours. After this period, queries return the task status as UNKNOWN.

Request parameters

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.

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

outputobjectThe task's output.

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_urlstringReturned 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 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. Calculated only for successful tasks.

Properties

input_video_duration integerThe duration of the input video, in seconds.output_video_duration integerThe duration of the output video, in seconds.duration integerThe total video duration used for billing.SR integerThe resolution of the output video.video_count integerThe number of output videos. This value is always 1.

request_id stringUnique request identifier for tracing and troubleshooting.

Task successful
Task failed
Task query expired

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

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

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 parameter is invalid."
    }
}

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 a call fails, check the error messages reference.

FAQ

Video aspect ratio

Output aspect ratio matches the first frame. Unlike the HappyHorse text-to-video model, image-to-video does not support the ratio parameter.

​Usage notes

​HTTP calls

​Step 1: Create a task

Request parameters

Request body

Response parameters

​Step 2: Poll for the result

Request parameters

Request headers

Path parameters

Response parameters

​Error codes

​FAQ

​Video aspect ratio

Usage notes

HTTP calls

Step 1: Create a task

Step 2: Poll for the result

Error codes

FAQ

Video aspect ratio