DataEyes HappyHorse Image-to-Video (First Frame) API Reference

Overview

The DataEyes HappyHorse Image-to-Video (First Frame) API generates video clips from a single input image used as the first frame. An optional text prompt can guide the video content. The API operates asynchronously: you submit a generation task and then poll for the result.

Available Models:

Model ID	Description
`happyhorse-1.1-i2v`	HappyHorse v1.1 Image-to-Video
`happyhorse-1.0-i2v`	HappyHorse v1.0 Image-to-Video

Base URL

https://platform.dataeyes.ai/ali

Authentication

All requests require a valid API key passed in the Authorization header using the Bearer scheme.

Authorization: Bearer sk-xxxx

Test Key (for development only):

sk-your-api-key

Asynchronous Workflow

The API follows a two-step asynchronous pattern:

Submit a video generation task via POST. The response returns a task_id.

Poll the task status via GET using the task_id until the status is SUCCEEDED or FAILED.

Recommended polling interval: every 15 seconds. Query rate limit: 20 requests per second.

Task IDs and generated video URLs are valid for 24 hours after creation.

Step 1: Create a Video Generation Task

Endpoint

POST /api/v1/services/aigc/video-generation/video-synthesis

Required Headers

Header	Value
`Content-Type`	`application/json`
`Authorization`	`Bearer sk-xxxx`
`X-DashScope-Async`	`enable`

Request Body

Field	Type	Required	Description
`model`	string	Yes	Model identifier. One of `happyhorse-1.1-i2v` or `happyhorse-1.0-i2v`.
`input`	object	Yes	Input specification containing the prompt and media.
`input.prompt`	string	No	Text prompt describing desired video content. Maximum 5,000 non-Chinese characters or 2,500 Chinese characters. Unlike the text-to-video API, this field is optional for image-to-video.
`input.media`	array	Yes	Array containing exactly 1 media element specifying the first frame image.
`input.media[].type`	string	Yes	Fixed value: `"first_frame"`.
`input.media[].url`	string	Yes	Public URL (HTTP or HTTPS) to the image, or a Base64-encoded data URI in the format `data:{MIME};base64,{data}`.
`parameters`	object	No	Generation parameters (see below).

Parameters Object

Field	Type	Required	Default	Description
`resolution`	string	No	`"1080P"`	Output resolution. Accepted values: `720P`, `1080P`. The model auto-scales total pixel count to match the target resolution. Output aspect ratio follows the input first frame image.
`duration`	integer	No	`5`	Video duration in seconds. Range: `[3, 15]`.
`watermark`	boolean	No	`true`	Whether to include a watermark on the generated video.
`seed`	integer	No	(random)	Random seed for reproducibility. Range: `[0, 2147483647]`.

Note: The ratio parameter is not supported for image-to-video generation. The output aspect ratio is determined automatically by the input first frame image.

Image Constraints

Constraint	Requirement
Supported formats	JPEG, JPG, PNG, WEBP
Minimum dimensions	Width >= 300 px, Height >= 300 px
Aspect ratio	Between 1:2.5 and 2.5:1
Maximum file size	20 MB

MIME Types for Base64 Data URIs:

Format	MIME Type
JPEG / JPG	`image/jpeg`
PNG	`image/png`
WEBP	`image/webp`

Example Request

Example Response

{
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "output": {
    "task_id": "ab123456-cd78-ef90-1234-567890abcdef",
    "task_status": "PENDING"
  }
}

Step 2: Query Task Status

Endpoint

GET /api/v1/tasks/{task_id}

Required Headers

Header	Value
`Authorization`	`Bearer sk-xxxx`

Path Parameters

Parameter	Type	Description
`task_id`	string	The task ID returned from Step 1.

Example Request

Example Response (SUCCEEDED)

{
  "request_id": "f0e1d2c3-b4a5-6789-0abc-def123456789",
  "output": {
    "task_id": "ab123456-cd78-ef90-1234-567890abcdef",
    "task_status": "SUCCEEDED",
    "video_url": "https://cdn.example.com/generated-video.mp4"
  },
  "usage": {
    "duration": 5,
    "input_video_duration": 0,
    "output_video_duration": 5,
    "video_count": 1,
    "SR": 0
  }
}

Video output format: MP4, H.264 codec, 24 fps.

Usage Fields

Field	Type	Description
`duration`	integer	Requested video duration in seconds.
`input_video_duration`	integer	Input video duration. Fixed `0` for image-to-video tasks.
`output_video_duration`	integer	Actual output video duration in seconds.
`video_count`	integer	Number of videos generated. Fixed `1`.
`SR`	integer	Super-resolution flag.

Task Status Reference

Status	Description
`PENDING`	Task has been accepted and is queued for processing.
`RUNNING`	Task is actively generating the video.
`SUCCEEDED`	Video generation completed successfully. The `video_url` field is populated.
`FAILED`	Task failed. Check the error message in the response for details.
`CANCELED`	Task was canceled before completion.
`UNKNOWN`	Task status could not be determined.

Python Example

FAQ

How is the output aspect ratio determined?

For image-to-video (first frame) generation, the output aspect ratio is determined automatically by the input first frame image. The ratio parameter is not supported for i2v tasks (unlike text-to-video). The model reads the dimensions of the provided image and generates a video matching that aspect ratio. The resolution parameter controls the total pixel count (720P or 1080P), but the aspect ratio always follows the input image.

Is the prompt required for image-to-video?

No. Unlike the text-to-video API, the input.prompt field is optional for image-to-video generation. If omitted, the model will infer motion and content from the first frame image alone. Providing a prompt can help guide the generated motion and scene evolution.

How long are task IDs and video URLs valid?

Both task IDs and generated video URLs expire 24 hours after creation. Download or consume the video within this window.

What polling interval should I use?

Poll every 15 seconds. The query endpoint has a rate limit of 20 requests per second.

Notes

The X-DashScope-Async: enable header is required on the creation request. Omitting it will result in an error.

The input.media array must contain exactly one element with type set to "first_frame".

When using Base64 data URIs, the format must be data:{MIME};base64,{data} with the correct MIME type for the image format.

The ratio parameter (used in text-to-video) is not applicable to image-to-video and will be ignored or cause an error if provided.

Video output is encoded as MP4 with H.264 codec at 24 fps.

Error Codes

Error Code	HTTP Status	Description
`InvalidApiKey`	401	The API key is missing, malformed, or invalid. Verify the `Authorization` header value.
`InvalidParameter`	400	One or more request parameters are invalid. Check field values, image constraints, and required fields.
`Throttling`	429	Request rate limit exceeded. Reduce request frequency and retry after a brief delay.

HappyHorse Image-to-Video (First Frame)

DataEyes HappyHorse Image-to-Video (First Frame) API Reference#

Overview#

Base URL#

Authentication#

Asynchronous Workflow#

Step 1: Create a Video Generation Task#

Endpoint#

Required Headers#

Request Body#

Parameters Object#

Image Constraints#

Example Request#

Example Response#

Step 2: Query Task Status#

Endpoint#

Required Headers#

Path Parameters#

Example Request#

Example Response (SUCCEEDED)#

Usage Fields#

Task Status Reference#

Python Example#

FAQ#

How is the output aspect ratio determined?#

Is the prompt required for image-to-video?#

How long are task IDs and video URLs valid?#

What polling interval should I use?#

Notes#

Error Codes#

DataEyes HappyHorse Image-to-Video (First Frame) API Reference

Overview

Base URL

Authentication

Asynchronous Workflow

Step 1: Create a Video Generation Task

Endpoint

Required Headers

Request Body

Parameters Object

Image Constraints

Example Request

Example Response

Step 2: Query Task Status

Endpoint

Required Headers

Path Parameters

Example Request

Example Response (SUCCEEDED)

Usage Fields

Task Status Reference

Python Example

FAQ

How is the output aspect ratio determined?

Is the prompt required for image-to-video?

How long are task IDs and video URLs valid?

What polling interval should I use?

Notes

Error Codes