# Alibaba | HappyHorse 1.0 | Reference to Video

Reference to Video generation, offering enhanced stability in subject and scene referencing. Capable of processing up to 9 reference images, it precisely preserves creative intent to deliver superior performance.

## API Information

- **Model Slug:** alibaba-happyhorse-1-0-reference-to-video
- **Branded URL:** https://www.eachlabs.ai/alibaba/happyhorse-1-0/alibaba-happyhorse-1-0-reference-to-video
- **Provider:** Alibaba
- **Category:** Reference to Video
- **Output Type:** video
- **Status:** active
- **Base Cost:** $0.14–$0.24 per second, depending on resolution
- **Estimated Processing Time:** 220 seconds
- **Interactive Demo:** https://www.eachlabs.ai/ai-models/alibaba-happyhorse-1-0-reference-to-video

## Pricing

- **Charge Type:** dynamic
- **Estimate:** $0.14–$0.24 per second, depending on resolution
- **Pricing Details:** 720P: $0.14
- **Pricing Details:** default: $0.24

## Input Schema

| Parameter | Type | Required | Default | Constraints | Description |
|-----------|------|----------|---------|-------------|-------------|
| prompt | string | Yes | - | - | Text description of the video. Use 'character1', 'character2', ... in your prompt to reference each entry of Reference Images by array order. Supports any language. Maximum 5,000 non-Chinese characters or 2,500 Chinese characters; excess is automatically truncated. |
| reference_images | array | Yes | - | - | 1-9 reference images. Each image's order in this list maps to character1, character2, ... in the prompt. Format: JPEG, JPG, PNG, WEBP. Shortest side at least 400 px (720P or higher recommended). Max 10 MB per image. |
| resolution | string | No | 1080P | 720P, 1080P | Output video resolution. 720P: lower cost, faster generation. 1080P: higher quality (default). |
| ratio | string | No | 16:9 | 16:9, 9:16, 1:1, 4:3, 3:4 | Output video aspect ratio. 16:9: landscape (default). 9:16: portrait/vertical. 1:1: square. 4:3: standard. 3:4: vertical standard. |
| duration | integer | No | 5 | 3–15 | Video duration in seconds. Range: 3-15. Each second is billed separately. Default: 5. |
| seed | integer | No | - | 0–2147483647 | Seed for reproducibility. Range [0, 2147483647]. Same seed produces similar (not identical) results because generation is probabilistic. Random if omitted. |

## Example Request

```bash
curl -X POST https://api.eachlabs.ai/v1/prediction/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "alibaba-happyhorse-1-0-reference-to-video",
  "input": {
    "prompt": "A woman in a royal blue midi dress character1. The shot opens with a side medium view outlining the sharp tailored fit of the dress against the white studio backdrop. The shot cuts to a low-angle view as she holds the open blue and white geometric umbrella character2 above her, slowly rotating it over her shoulder. She turns her gaze directly to camera, expression cool and editorial.",
    "reference_images": [
      "https://cdn-us.eachlabs.ai/defaults/cbd6359851940b15153759a132961f0bb9e002a26dd31a214a92a0d9b234ff89.png",
      "https://cdn-us.eachlabs.ai/defaults/a904fb89ba718ccbca31102b82ade5a63a9c013bebb52e1f0161456ddf53f667.png"
    ]
  }
}'
```

## Output Schema

Response returned by `GET /v1/prediction/{id}` when the job completes:

```json
{
  "status": "success",
  "predictionID": "string",
  "output": "string (URL of generated video)",
  "metrics": {
    "predict_time": "number (seconds)"
  }
}
```

## Polling

```bash
curl https://api.eachlabs.ai/v1/prediction/{PREDICTION_ID} \
  -H "Authorization: Bearer YOUR_API_KEY"
```

| Status | Meaning |
|--------|---------|
| `processing` | Still running — poll again |
| `success` | Done — read `output` |
| `error` | Failed — read `message` / `details` |

## Webhook (alternative to polling)

Pass `"webhook_url": "https://your.host/path"` in the create request. Eachlabs POSTs this payload when the job ends:

```json
{
  "exec_id": "prediction-uuid",
  "status": "succeeded",
  "output": "https://...",
  "error": ""
}
```

`status` is `"succeeded"` or `"failed"`. `exec_id` equals the `predictionID` from create. Return 2xx within 30 seconds.

## Errors

Error body: `{ "status": "error", "message": "...", "details": "..." }`

| Code | Meaning |
|------|---------|
| `400` | Invalid input |
| `401` | Missing / invalid `Authorization` bearer token |
| `404` | Unknown model or prediction id |
| `429` | Rate limit — 100 creates / min, 10 concurrent per key |
| `5xx` | Retry with backoff |

## Overview

**Alibaba | HappyHorse 1.0 | Reference to Video Overview**

Alibaba | HappyHorse 1.0 | Reference to Video is a unified AI video generation model that transforms text prompts and reference images into high-fidelity 1080p video with synchronized audio in a single pass. Developed by Alibaba's ATH AI Innovation Unit, this model solves the critical problem of maintaining visual consistency and creative intent across video generation by processing up to 9 reference images while preserving subject identity and scene coherence. The standout differentiator is its native audio-video co-generation architecture—dialogue, ambient sounds, and Foley effects are synthesized alongside visuals rather than stitched together afterward, resulting in superior lip-sync accuracy across seven languages and eliminating time-consuming post-production resynchronization.

## Usage Notes

- API Base URL: `https://api.eachlabs.ai/v1`
- Authentication: send `Authorization: Bearer YOUR_API_KEY`. Generate a key from the Eachlabs dashboard at https://www.eachlabs.ai/dashboard/api-keys.
- File-typed parameters (`*_url`, `image_url`, `video_url`, `audio_url`, etc.) accept publicly-reachable HTTPS URLs only. Upload your asset first (GCS / S3 / your CDN) and pass the resulting URL. Data-URIs and localhost URLs are rejected.
- For structured parameters (arrays / objects) send real JSON values, not stringified payloads.
- Monetary values are reported in USD; per-token / per-megapixel rates may be billed in micro-cents internally.
- Prefer `webhook_url` over polling for long-running predictions — see the Webhook Callback section.