Happy Horse 1.1 Reference to Video API

Happy Horse 1.1 Reference to Video

Happy Horse 1.1 Reference to Video solves identity drift across multi-shot narratives and complex scene staging. Submit 1 to 9 reference images representing one or more characters, garments, props, or background environments via public URLs, Data URIs, or Base64. A required prompt of up to 2,500 characters directs actions, dialogue, interactions, and camera choreography while preserving identity, rendering synchronized sound, and framing into your choice of 9 aspect ratios.

Key Capabilities & Advantages

• Multi-image reference conditioning (1–9 images)Accepts 1 to 9 reference images to define multiple camera angles, costumes, distinct characters, or key props within a single generation task.

• Multi-character identity anchoringMaintains separate visual identities for multiple characters across interaction scenes, preventing facial swapping or blending.

• Flexible prompt-based character bindingBinds reference images either naturally through detailed descriptive prompts or explicitly using bracketed tokens like [image_1] and [image_2].

• Native synchronized dialogue and FoleySynthesizes vocal lines with accurate lip movements and environment Foley simultaneously without third-party audio pipelines.

• Multi-angle visual groundingCombines front, side, and three-quarter view reference photos to construct consistent 3D volume through complex camera orbits.

• Nine native aspect ratio framingsProvides full flexibility with 9 supported aspect ratios including 16:9, 9:16, 21:9, and 1:1, independent of reference image dimensions.

Parameters

How to Call Happy Horse 1.1 Reference to Video API

1. 01

   Prepare 1–9 reference imagesCollect clear reference images of your subjects, props, or costumes with distinct details.

2. 02

   Pass ordered reference arrayProvide the image URLs or data strings inside the reference_image_urls parameter array.

3. 03

   Draft direction promptWrite a required prompt (up to 2,500 chars) detailing scene events, speaker dialogue, and character interactions.

4. 04

   Select duration, resolution, and ratioChoose 3 to 15 seconds, pick 720p or 1080p, and select your preferred framing from 9 aspect ratios.

5. 05

   Trigger asynchronous generationSubmit your payload to the unified endpoint or trigger via the interactive playground.

6. 06

   Download the consistent videoQuery progress with task_id until finished, then access the rendered video via data.files[].file_url.

Pricing

Cost = output seconds × resolution rate. 1 credit = $0.005; all three modes use the same rates. Failed tasks are refunded automatically.

Best Use Cases

• Multi-scene episodic video and web dramaKeep recurring actors and signature costumes looking identical across consecutive shots, dialogue scenes, and action sequences.

• Multi-character dialogue scenesSupply separate reference portraits for two or more characters having a conversation with alternating dialogue and synchronized lip motion.

• Consistent commercial brand assetsFeature proprietary mascots, corporate ambassadors, or packaged goods across diverse seasonal advertising campaigns.

• Virtual fashion and product lookbooksShowcase garments and accessories on consistent models under varying lighting conditions, movement dynamics, and settings.

Pro Tips

• When directing two characters, supply portrait photos for each and use explicit references in your prompt (e.g. 'The woman in blue [image_1] speaks in English, while the man in jacket [image_2] listens attentively') to avoid identity mix-ups.
• Providing multiple angles of the same character (front, profile, three-quarter) allows the model to render smooth 360-degree orbit cameras without feature deformation.
• Ensure reference images are well-illuminated and sharp; avoid heavy compression or extreme lens distortion for optimal fidelity.
• Unlike Image to Video which inherits the first frame's ratio, Reference to Video requires an explicit aspect_ratio choice; select the format that matches your distribution channel.

Usage Notes

• reference_image_urls accepts between 1 and 9 image URLs; providing an empty array causes task rejection before deduction.
• A nonblank prompt is required (up to 2,500 characters) to define the action and role of the references in the scene.
• Aspect ratio is configurable (defaults to 16:9); choose from 9 native ratios regardless of reference image dimensions.
• Generates embedded audio with character speech, Foley, and music in the final MP4 file.