Skip to main content

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.

Alibaba ATH Happy Horse 1.0 integration

Happy Horse 1.0 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.
Happy Horse 1.0 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: From the same family that ranks #1 on the Artificial Analysis Video Arena (April 2026)
  • Up to 9 reference images: More references than competing models for richer multi-character scenes
  • Indexed prompt references: Use character1..character9 tokens in the prompt to place each reference
  • 5 aspect ratios: 16:9, 9:16, 1:1, 4:3, 3:4
  • 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.

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

Create a new reference-to-video generation task

GET /v1/ai/reference-to-video/happy-horse-1

List all Happy Horse 1.0 R2V tasks with status

GET /v1/ai/reference-to-video/happy-horse-1/{task-id}

Get task status and results by ID

​
Parameters

ParameterTypeRequiredDefaultDescription
promptstringYes-Scene description referencing characters as character1..character9. Max 5000 characters
image_urlsarrayYes-Ordered array of 1 to 9 reference images (JPEG/JPG/PNG/WEBP, max 10 MB each). Position determines character index
aspect_ratiostringNo"16:9"Output ratio: "16:9", "9:16", "1:1", "4:3", "3:4"
resolutionstringNo"1080P"Output resolution: "720P" or "1080P"
durationintegerNo5Video length in seconds: 3 to 15
watermarkbooleanNofalseAdd a bottom-right “Happy Horse” text watermark
seedintegerNoRandomSeed for reproducibility (0 to 2147483647)
webhook_urlstringNo-URL for async status notifications

​
Frequently Asked Questions

Happy Horse 1.0 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.
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.”
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.
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.
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).
Happy Horse 1.0 R2V supports integer durations from 3 to 15 seconds. The default is 5 seconds.
Rate limits depend on your subscription tier. See the Rate Limits page for current limits by plan.
See the Pricing page for current rates and subscription options.

​
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.