DataEyes HappyHorse Reference-to-Video API Reference

Overview

The DataEyes HappyHorse Reference-to-Video API generates videos by fusing subjects extracted from one or more reference images into a coherent video clip, guided by a text prompt. The API supports up to nine reference images per request, enabling multi-subject composition within a single generated video.

Available Models:

Model	Description
`happyhorse-1.1-r2v`	Latest generation, improved subject fidelity and motion quality
`happyhorse-1.0-r2v`	First-generation reference-to-video model

Endpoint

Base URL: https://platform.dataeyes.ai/ali

Method	Path	Purpose
`POST`	`/api/v1/services/aigc/video-generation/video-synthesis`	Create a video generation task
`GET`	`/api/v1/tasks/{task_id}`	Query task status and retrieve results

Authentication

All requests must include the following headers:

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

Test Key: sk-your-api-key

The X-DashScope-Async header is mandatory. All video generation requests are processed asynchronously.

Workflow

The API follows an asynchronous task workflow:

1. POST  /video-synthesis       -->  Receive task_id
2. GET   /tasks/{task_id}       -->  Poll until SUCCEEDED or FAILED
3. Extract video URL from response

Poll every 15 seconds. Do not exceed 20 queries per second (RPS).

The returned task_id and video download URL are valid for 24 hours.

Step 1: Create a Video Generation Task

Request

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

Request Body

{
  "model": "happyhorse-1.1-r2v",
  "input": {
    "prompt": "[Image 1] the woman in a red cheongsam walks along the Great Wall at sunset",
    "media": [
      {
        "type": "reference_image",
        "url": "https://example.com/reference-photo.jpg"
      }
    ]
  },
  "parameters": {
    "resolution": "1080P",
    "ratio": "16:9",
    "duration": 5,
    "watermark": true,
    "seed": 42
  }
}

Field Reference

Top-Level

Field	Type	Required	Description
`model`	string	Yes	Model identifier. One of `happyhorse-1.1-r2v`, `happyhorse-1.0-r2v`.

`input`

Field	Type	Required	Description
`input.prompt`	string	Yes	Text prompt describing the desired video. Use `[Image N]` placeholders to reference items in the `media` array by position (1-indexed). See Prompt Referencing below.
`input.media`	array	Yes	Array of 1 to 9 reference image objects.

`input.media[]`

Field	Type	Required	Description
`type`	string	Yes	Fixed value: `"reference_image"`.
`url`	string	Yes	Public URL or Base64-encoded image data.

`parameters`

Field	Type	Required	Default	Description
`resolution`	string	No	`"1080P"`	Output resolution. Values: `720P`, `1080P`.
`ratio`	string	No	`"16:9"`	Aspect ratio. Values: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `4:5`, `5:4`, `9:21`, `21:9`.
`duration`	integer	No	`5`	Video duration in seconds. Range: 3 to 15.
`watermark`	boolean	No	`true`	Whether to apply a watermark to the output video.
`seed`	integer	No	Random	Random seed for reproducibility. Range: 0 to 2,147,483,647.

Prompt Referencing

The prompt field uses positional placeholders to bind reference images to subjects described in the text. Each placeholder takes the form [Image N], where N corresponds to the 1-based index of an element in the media array.

Rules:

Every [Image N] placeholder must be followed by a concrete description of the subject in that image (e.g., person, object, animal).

N must be within the range [1, len(media)].

You may reference the same image multiple times.

Examples:

Media Count	Prompt
1 image	`"[Image 1] the woman in a red cheongsam walks along the Great Wall at sunset"`
2 images	`"[Image 1] the golden retriever and [Image 2] the young boy play fetch in a park"`
3 images	`"[Image 1] the sports car drifts around [Image 2] the racetrack while [Image 3] the crowd cheers"`

Image Constraints

Constraint	Value
Supported formats	JPEG, JPG, PNG, WEBP
Minimum short edge	400 px
Recommended quality	720P or higher, clear images
Maximum file size	20 MB

MIME Types:

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

Response

{
  "request_id": "req-xxxxxxxx",
  "output": {
    "task_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "task_status": "PENDING"
  }
}

Step 2: Query Task Status

Request

GET /api/v1/tasks/{task_id}

Replace {task_id} with the value returned in Step 1.

Response (Succeeded)

{
  "request_id": "req-xxxxxxxx",
  "output": {
    "task_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "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,
    "ratio": "16:9"
  }
}

Usage Fields

Field	Type	Description
`duration`	integer	Requested duration in seconds.
`input_video_duration`	integer	Input video duration. Fixed `0` for reference-to-video (no input video).
`output_video_duration`	integer	Actual output video duration in seconds.
`video_count`	integer	Number of generated videos. Fixed `1`.
`SR`	integer	Super-resolution indicator.
`ratio`	string	Aspect ratio of the generated video.

Task Status

Status	Description
`PENDING`	Task has been accepted and is queued for processing.
`RUNNING`	Video generation is in progress.
`SUCCEEDED`	Generation completed successfully. Video URL is available.
`FAILED`	Generation failed. Check the error message in the response.
`CANCELED`	Task was canceled.
`UNKNOWN`	Status could not be determined.

Python Example

Notes

Asynchronous only. The X-DashScope-Async: enable header is mandatory. There is no synchronous generation endpoint.

Polling interval. Poll no more frequently than every 15 seconds. The query endpoint enforces a rate limit of 20 RPS.

URL expiry. Both the task_id and the returned video URL expire after 24 hours. Download the video promptly.

Image quality. For best results, use clear reference images at 720P resolution or higher. The short edge of every image must be at least 400 pixels.

Prompt specificity. Always describe the concrete subject in each referenced image. Generic prompts such as "[Image 1] generates a video" will produce poor results. Instead, specify what the subject is: "[Image 1] the woman in a red cheongsam".

Multi-subject composition. When using multiple reference images, each [Image N] placeholder should identify a distinct subject. The model fuses all referenced subjects into a single coherent video.

Seed reproducibility. Setting the seed parameter to a fixed value enables approximate reproducibility across runs with the same inputs and parameters.

Base64 input. When providing Base64-encoded image data in the url field, supply the raw Base64 string without a data: URI prefix.

Error Codes

Error Code	HTTP Status	Description	Resolution
`InvalidApiKey`	401	The API key is missing, malformed, or revoked.	Verify the `Authorization` header contains a valid `Bearer` token.
`InvalidParameter`	400	One or more request parameters are invalid.	Check the error message for the specific field. Common causes: unsupported ratio, duration out of range, missing prompt, image too small, or media array empty/exceeding 9 elements.
`Throttling`	429	Request rate limit exceeded.	Reduce request frequency. Implement exponential backoff and retry after the period indicated in the response.

HappyHorse Reference-to-Video

DataEyes HappyHorse Reference-to-Video API Reference#

Overview#

Endpoint#

Authentication#

Workflow#

Step 1: Create a Video Generation Task#

Request#

Request Body#

Field Reference#

Top-Level#

input#

input.media[]#

parameters#

Prompt Referencing#

Image Constraints#

Response#

Step 2: Query Task Status#

Request#

Response (Succeeded)#

Usage Fields#

Task Status#

Python Example#

Notes#

Error Codes#

DataEyes HappyHorse Reference-to-Video API Reference

Overview

Endpoint

Authentication

Workflow

Step 1: Create a Video Generation Task

Request

Request Body

Field Reference

Top-Level

`input`

`input.media[]`

`parameters`

Prompt Referencing

Image Constraints

Response

Step 2: Query Task Status

Request

Response (Succeeded)

Usage Fields

Task Status

Python Example

Notes

Error Codes