All Products
Search

This Product

    Alibaba Cloud Model Studio:HappyHorse image-to-video (first frame) API reference

    Document Center

    Alibaba Cloud Model Studio:HappyHorse image-to-video (first frame) API reference

    Last Updated:Apr 26, 2026

    The HappyHorse image-to-video model generates physically realistic videos with smooth motion from a single image and an optional text description.

    Availability

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

    Note

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

    HTTP request

    Image-to-video tasks typically take 1 to 5 minutes, so the API uses asynchronous calls. The workflow has two steps: "Create a task -> Poll for results", as described below:

    Step 1: Create a task and get the task ID

    Singapore

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

    Beijing

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

    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 (first frame)

    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 to use for video generation.

    Valid values:

    • happyhorse-1.0-i2v

    input object (Required)

    Input for the model.

    Properties

    prompt string (Optional)

    The text description of the video to generate.

    Supports Chinese and English. Maximum 2,500 characters; excess is truncated.

    media array (Required)

    Input media list. Specifies the image for video generation. The aspect ratio of the generated video automatically follows the input image.

    media[] element properties

    type string (Required)

    Media asset type. Valid values:

    • first_frame

    Constraint: Exactly one first frame image is required.

    url string (Required)

    URL of the media asset.

    Input image (type=first_frame)

    URL of the first frame image. HTTP and HTTPS protocols are supported.

    Image constraints:

    • Format: JPEG, JPG, PNG, BMP, WEBP.

    • Resolution: Width and height must be at least 300 pixels.

    • Aspect ratio: 1:2.5 to 2.5:1.

    • File size: Up to 10 MB.

    parameters object (Optional)

    Video parameters such as resolution and duration.

    Properties

    resolution string (Optional)

    Resolution of the generated video.

    The model automatically scales to approximate the total pixel count for the selected resolution. The aspect ratio of the output video closely matches the input first frame.

    Valid values:

    • 720P

    • 1080P (default)

    duration integer (Optional)

    Duration of the generated video, in seconds.

    • happyhorse-1.0-i2v: Must be between 3 and 15. Defaults to 5.

    watermark boolean (Optional)

    Whether to add a watermark to the generated video. The watermark appears in the lower-right corner with the text "HappyHorse".

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

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

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

    output object

    Task output information.

    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: Query the result by task ID

    Singapore

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

    Beijing

    GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_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 -X GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
    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 succeeded

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

    Task failed

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

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

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

    output object

    Task output information.

    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.

    The link is valid for 24 hours. Video frame rate: 24fps, MP4 format (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 messages.

    message string

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

    usage object

    Output statistics. Only successful results are counted.

    Properties

    input_video_duration integer

    Duration of the input video, in seconds.

    output_video_duration integer

    Duration of the output video, in seconds.

    duration integer

    Total video duration, used for billing.

    SR integer

    Resolution of the output video.

    video_count integer

    Number of output videos. Fixed to 1.

    request_id string

    Unique request identifier for tracing and troubleshooting.

    Error codes

    If the API call fails, see Error messages for troubleshooting.

    FAQ

    How is the aspect ratio determined?

    The aspect ratio of the image-to-video output automatically follows the input first frame image. Unlike HappyHorse - text-to-video, image-to-video does not support the ratio parameter.