DocsICP FilingConsole
官方文档
首页

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

更新时间：
复制 MD 格式
产品详情
我的收藏

Generate realistic, smooth-motion videos from a first-frame image and an optional text prompt using the HappyHorse model.

Usage notes

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 China (Beijing) 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

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

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.

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

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

Request parameters

Image-to-video

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-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.1-i2v

  • happyhorse-1.0-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:

  1. Public URL:

    • HTTP and HTTPS are supported.

    • Example: https://xxx/xxx.png.

  2. 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:

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

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

message string

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

Step 2: Poll for the result

China (Beijing)

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

Replace WorkspaceId with your actual Workspace ID.

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}

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.

  • RPS limit: The default RPS for the query API is 20. For higher-frequency queries or event notifications, we recommend that you configure an asynchronous task callback.

  • More operations: For batch queries, task cancellation, and other operations, see Manage asynchronous tasks.

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}.cn-beijing.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.
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.

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

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

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

message string

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

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

Previous：HappyHorse - text-to-videoNext：HappyHorse - reference-to-video