---
title: "Happy Horse 1.0 - Create video from reference images"
method: POST
path: "/v1/ai/reference-to-video/happy-horse-1"
tags: ["reference-to-video"]
---

# Happy Horse 1.0 - Create video from reference images

`POST /v1/ai/reference-to-video/happy-horse-1`

## Request

- Base URL: `https://api.magnific.com`
- URL: `https://api.magnific.com/v1/ai/reference-to-video/happy-horse-1`
- Auth: API key in header `x-magnific-api-key`

Generate a high-quality AI video guided by 1 to 9 reference images that define characters, objects or scenes using Happy Horse 1.0, Alibaba's reference-to-video model.

**How to use references:**
- Provide 1 to 9 reference images via `image_urls`
- Reference each image in the prompt by its 1-based positional index (`character1`, `character2`, ...)
- The order of `image_urls` matches the character index in the prompt

**Key features:**
- 720P and 1080P resolution support
- 5 aspect ratio options
- Duration range: 3-15 seconds
- Optional bottom-right "Happy Horse" watermark
- Prompt up to 5000 characters

## Request body

- R2vRequest1: Generate video guided by 1 to 9 reference images that define characters, objects or scenes using Happy Horse 1.0. In the prompt, reference each image by its 1-based positional index (`character1`, `character2`, ...). The order matches the array order.
  - `webhook_url` string, uri: Optional callback URL that will receive asynchronous notifications whenever the task changes status. The payload sent to this URL is the same as the corresponding GET endpoint response, but without the data field.
  - `prompt` string, required: Text prompt describing the desired elements and visual style of the generated video. Supports any language. Requests with prompts longer than 5000 characters are rejected by validation; the upstream provider further treats 5000 non-Chinese characters or 2500 Chinese characters as the effective ceiling. Use `character1`, `character2`, ... in the prompt to reference the corresponding image in the `image_urls` array; the order matches the array order. **Example:** "character1 and character2 walk together through a sunlit forest path"
  - `image_urls` ReferenceImage[], required: Ordered array of reference images. Array position determines the character reference number in the prompt (1st item → `character1`, 2nd → `character2`, etc.). **Supported formats:** JPEG, JPG, PNG, WEBP **Recommended resolution:** shortest side at least 400 px (720P or higher recommended) **Maximum file size:** 10 MB per image
    - `url` string, uri, required: Publicly accessible URL of the reference image. **Supported formats:** JPEG, JPG, PNG, WEBP **Recommended resolution:** shortest side at least 400 px (720P or higher recommended) **Maximum file size:** 10 MB
  - `aspect_ratio` '16:9' | '9:16' | '1:1' | '4:3' | '3:4': Output video aspect ratio: - `16:9`: Landscape (widescreen) - `9:16`: Portrait (vertical, mobile-optimized) - `1:1`: Square - `4:3`: Standard landscape - `3:4`: Standard portrait
  - `resolution` '720P' | '1080P': Output video resolution: - `720P`: 720p HD (1280x720) - `1080P`: 1080p Full HD (1920x1080)
  - `duration` integer: Duration of the generated video in seconds.
  - `watermark` boolean: Whether to add a watermark to the generated video. The watermark appears in the bottom-right corner with the fixed text "Happy Horse".
  - `seed` integer: Random seed for reproducibility. Use the same seed with identical parameters to improve reproducibility (does not guarantee identical results). Leave unset for a random seed.

## Response `200`

OK - The task exists and the status is returned

- InlineObject4
  - `data` TaskDetail1, required
    - `task_id` string, uuid, required: Task identifier
    - `status` 'CREATED' | 'IN_PROGRESS' | 'COMPLETED' | 'FAILED', required: Task status
    - `generated` string[], required

## Other responses

- `400`: Bad Request - The server could not understand the request due to invalid syntax.
- `401`: Unauthorized - The client must authenticate itself to get the requested response.
- `500`: Internal Server Error - The server has encountered a situation it doesn't know how to handle.
- `503`: Service Unavailable

---

[API](https://skmtc.dev/magnific/apis/magnific-api.md) · [All operations](https://skmtc.dev/magnific/apis/magnific-api/llms.txt) · [OpenAPI document](https://skmtc.dev/magnific/apis/magnific-api/revisions/60711fb082c7?raw)