> ## Documentation Index
> Fetch the complete documentation index at: https://docs.magnific.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Happy Horse 1.1 Reference To Video API

> Generate AI videos from up to 9 reference images with Happy Horse 1.1. Reference characters as character1..character9 in the prompt. 720P/1080P, 9 aspect ratios.

<Card title="Alibaba ATH Happy Horse 1.1 integration" icon="video">
  Happy Horse 1.1 Reference-to-Video generates videos from up to 9 reference images, preserving character identity across scenes. Reference each image in the prompt with `character1`..`character9` tokens.
</Card>

Happy Horse 1.1 Reference-to-Video is an AI video generation API that creates MP4 videos guided by 1 to 9 reference images defining characters, objects, or scenes. Built by Alibaba ATH (Taotian Innovation Unit, led by Zhang Di), the model maintains visual identity across the generated video. You reference each image in the prompt by its 1-based positional index (`character1`, `character2`, ..., up to `character9`). Output is available at 720P (1280x720) or 1080P (1920x1080) with durations from 3 to 15 seconds.

### Key capabilities

* **State-of-the-art quality**: Latest iteration of the Alibaba ATH Happy Horse video family
* **Up to 9 reference images**: Rich multi-character scenes from a single request
* **Indexed prompt references**: Use `character1`..`character9` tokens in the prompt to place each reference
* **9 aspect ratios**: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `21:9`, `9:21`, `5:4`, `4:5`
* **Resolution options**: 720P (1280x720) and 1080P (1920x1080) output
* **Flexible durations**: 3 to 15 seconds of video output (default 5 seconds)
* **Optional watermark**: Bottom-right "Happy Horse" text watermark, off by default
* **Long prompts**: Up to 5000 characters describing scene, motion, and character interactions
* **Async processing**: Webhook notifications or polling for task completion

### How character references work

1. Provide 1 to 9 character images in the `image_urls` array (JPEG/JPG/PNG/WEBP, shortest side 400 px+ recommended, max 10 MB each)
2. The 1st item in the array is `character1`, the 2nd is `character2`, ..., up to `character9`
3. In the `prompt`, reference characters by these tokens to place them in the scene
4. Combine multiple references for multi-character scenes (e.g. "character1 and character2 share a meal")

**Example prompt:**

> "character1 and character2 walk together through a sunlit forest path, golden hour lighting"

### Use cases

* **Multi-character narratives**: Create scenes with up to 9 distinct characters interacting
* **Branded content**: Maintain consistent mascot, spokesperson, or brand identity across video campaigns
* **Episodic content**: Reuse the same characters across multiple videos for series or storytelling
* **Game cinematics**: Generate cutscenes featuring specific character designs
* **Marketing campaigns**: Place product imagery (`character1` = product) into varied scene contexts
* **Storyboarding**: Pre-visualize scenes with reference characters before live production

### API operations

Generate videos by submitting reference images and a prompt to the API. The service returns a task ID for async polling or webhook notification.

<div className="my-11">
  <Columns cols={2}>
    <Card title="POST /v1/ai/reference-to-video/happy-horse-1-1" icon="video" href="/api-reference/reference-to-video/happy-horse-1-1/generate">
      Create a new reference-to-video generation task
    </Card>

    <Card title="GET /v1/ai/reference-to-video/happy-horse-1-1" icon="list" href="/api-reference/reference-to-video/happy-horse-1-1/happy-horse-1-1-r2v-tasks">
      List all Happy Horse 1.1 R2V tasks with status
    </Card>

    <Card title="GET /v1/ai/reference-to-video/happy-horse-1-1/{task-id}" icon="magnifying-glass" href="/api-reference/reference-to-video/happy-horse-1-1/task-by-id">
      Get task status and results by ID
    </Card>
  </Columns>
</div>

### Parameters

| Parameter      | Type            | Required | Default   | Description                                                                                                                                                                           |
| -------------- | --------------- | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `prompt`       | `string`        | Yes      | -         | Scene description referencing characters as `character1`..`character9`. Max 5000 characters                                                                                           |
| `image_urls`   | `array<object>` | Yes      | -         | Ordered array of 1 to 9 reference image objects, each `{ "url": "https://..." }` (JPEG/JPG/PNG/WEBP, max 10 MB each). Position determines character index. Objects, not plain strings |
| `aspect_ratio` | `string`        | No       | `"16:9"`  | Output ratio: `"16:9"`, `"9:16"`, `"1:1"`, `"4:3"`, `"3:4"`, `"21:9"`, `"9:21"`, `"5:4"`, `"4:5"`                                                                                     |
| `resolution`   | `string`        | No       | `"1080P"` | Output resolution: `"720P"` or `"1080P"`                                                                                                                                              |
| `duration`     | `integer`       | No       | `5`       | Video length in seconds: 3 to 15                                                                                                                                                      |
| `watermark`    | `boolean`       | No       | `false`   | Add a bottom-right "Happy Horse" text watermark                                                                                                                                       |
| `seed`         | `integer`       | No       | Random    | Seed for reproducibility (0 to 2147483647)                                                                                                                                            |
| `webhook_url`  | `string`        | No       | -         | URL for async status notifications                                                                                                                                                    |

Note that `image_urls` takes an array of **objects** (`{ "url": "https://..." }`), not plain strings. Example request body:

```json theme={null}
{
  "prompt": "character1 and character2 walk together through a sunlit forest path",
  "image_urls": [
    { "url": "https://example.com/character1.jpg" },
    { "url": "https://example.com/character2.jpg" }
  ],
  "aspect_ratio": "16:9",
  "resolution": "1080P",
  "duration": 5
}
```

When the task completes, the generated MP4 video URL is returned in `data.generated`. The URL is valid for 24 hours — download and persist it to permanent storage immediately.

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="How many character references can I use?">
    Happy Horse 1.1 Reference-to-Video accepts 1 to 9 reference images via the `image_urls` array. The first image is referenced as `character1`, the second as `character2`, and so on up to `character9`.
  </Accordion>

  <Accordion title="How do I reference characters in the prompt?">
    Use position-based tokens that match the order of the `image_urls` array. The 1st image is `character1`, the 2nd is `character2`, etc. Example: "character1 and character2 walk together through a sunlit forest path while character3 watches from a distance."
  </Accordion>

  <Accordion title="What image formats are supported for references?">
    Reference images must be JPEG, JPG, PNG, or WEBP via publicly accessible URLs. Recommended shortest side is at least 400 pixels (720P or higher recommended). Maximum file size is 10 MB per image.
  </Accordion>

  <Accordion title="What is the maximum prompt length?">
    The prompt can be up to 5000 characters. The upstream provider treats 5000 non-Chinese characters or 2500 Chinese characters as the effective ceiling. Prompts longer than 5000 characters are rejected by validation.
  </Accordion>

  <Accordion title="What is the watermark parameter?">
    When `watermark` is `true`, a fixed "Happy Horse" text watermark is rendered in the bottom-right corner of the output video. Default is `false` (no watermark).
  </Accordion>

  <Accordion title="What durations are available?">
    Happy Horse 1.1 R2V supports integer durations from 3 to 15 seconds. The default is 5 seconds.
  </Accordion>

  <Accordion title="What are the rate limits for Happy Horse 1.1?">
    Rate limits depend on your subscription tier. See the [Rate Limits](/ratelimits) page for current limits by plan.
  </Accordion>

  <Accordion title="How much does Happy Horse 1.1 cost?">
    See the [Pricing page](/pricing) for current rates and subscription options.
  </Accordion>
</AccordionGroup>

## Best practices

* **Reference images**: Use clear, well-lit images with the character or object prominently visible. Avoid busy backgrounds.
* **Reference order**: The array order is the character index — list characters in the order you plan to reference them in the prompt.
* **Prompt structure**: Explicitly name each character by token ("character1 walks left while character2 sits down") for predictable placement.
* **Image consistency**: Use images at similar quality and lighting for smoother integration in multi-character scenes.
* **Duration selection**: Start with shorter durations (3-5 seconds) for iteration, then increase for final outputs.
* **Production integration**: Use webhooks for scalable applications instead of polling.
* **Error handling**: Implement retry with exponential backoff for 503 errors during high-demand periods.

## Related APIs

* **[Happy Horse 1.1 Text-to-Video](/api-reference/text-to-video/happy-horse-1-1/overview)**: Generate videos from text prompts without character references
* **[Happy Horse 1.1 Image-to-Video](/api-reference/image-to-video/happy-horse-1-1/overview)**: Animate a single image into video
* **[Happy Horse 1.0 Reference-to-Video](/api-reference/reference-to-video/happy-horse-1/overview)**: Previous Happy Horse iteration with up to 9 character references