Happy Horse 1.0 Reference to Video API

alibaba/happyhorse-1.0/reference-to-video

Happy Horse 1.0 Reference to Video transforms 1–9 reference images and text prompts into cinematic short videos, with 3–15 second duration, 720p or 1080p output, and prompt-guided subject descriptions. It maintains consistent character identity, attire details, and artistic styling across camera movements while choreographing dynamic action in freshly framed narrative scenes.

Input

Prompt

259/2500

Reference images

Drag and drop files, paste from clipboard, or provide a URL.

Resolution

Duration

Aspect ratio

Seed

Safety checker

Output

Idle

Your generated video will appear here

Add your prompt and required media, review the settings, then click Run.

Continue with

Happy Horse 1.0 Text to Video Happy Horse 1.0 Image to Video Happy Horse 1.0 Video Edit

Examples

character1 stands at the workshop stage from character3 and brings the knight marionette character2 to life, making it bow and raise its wooden sword while warm lamp light flickers, cinematic slow push in, no text, no logos, no watermark, no promotional marks

character1 kneels in the meadow and sketches in the field sketchbook character2, pencil moving as wildflowers sway in a light breeze, vertical composition, soft overcast light, no text, no logos, no watermark, no promotional marks

character1 scans the horizon with brass binoculars as storm clouds gather and waves break against the rocks below the lighthouse, wind tugging at the wool sweater, slow cinematic orbit, no text, no logos, no watermark, no promotional marks

REST API

Quick Start

Authenticate via API Key, submit reference image assets alongside character tokens, and retrieve video via task ID.

Connect to Vidgo API

Create an API Key, store it securely on your server, and set Authorization: Bearer VIDGO_API_KEY.

Endpoint: POSThttps://api.vidgo.ai/api/generate/submit
Authentication: Authorization: Bearer VIDGO_API_KEY

Submit a Reference to Video Task

Set reference_image_urls and describe the subjects and actions in prompt; character markers are optional.

Submit Request

REQUEST_BODY=$(cat <<'JSON'
{
  "model": "alibaba/happyhorse-1.0/reference-to-video",
  "input": {
    "prompt": "character1 stands at the workshop stage from character3 and brings the knight marionette character2 to life, making it bow and raise its wooden sword while warm lamp light flickers, cinematic slow push in, no text, no logos, no watermark, no promotional marks",
    "duration": 5,
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "reference_image_urls": [
      "https://cdn.vidgo.ai/apis/models/alibaba/happyhorse-1.0/reference-to-video/v1/01/input-01.png",
      "https://cdn.vidgo.ai/apis/models/alibaba/happyhorse-1.0/reference-to-video/v1/01/input-02.png",
      "https://cdn.vidgo.ai/apis/models/alibaba/happyhorse-1.0/reference-to-video/v1/01/input-03.png"
    ]
  }
}
JSON
)

RESPONSE=$(curl --silent --show-error --fail-with-body \
  --request POST \
  --url "https://api.vidgo.ai/api/generate/submit" \
  --header "Authorization: Bearer $VIDGO_API_KEY" \
  --header "Content-Type: application/json" \
  --data "$REQUEST_BODY")

CODE=$(printf '%s' "$RESPONSE" | jq -r '.code // empty')
if [ "$CODE" != "0" ] && [ "$CODE" != "200" ]; then
  printf 'API error: %s
' "$RESPONSE" >&2
  exit 1
fi
printf '%s
' "$RESPONSE"

Await Results

Poll with task_id while status is not_started or running. Stop at finished or failed; read data.files[].file_url on success or data.error_message on failure.

Track Status

GET https://api.vidgo.ai/api/generate/status/{task_id}

Poll every 2 seconds, backing off for extended jobs. Continue only while not_started or running. Alternatively provide callback_url.

not_startedrunningfinishedfailed

Submit Response

{
  "code": 200,
  "data": {
    "task_id": "task-unified-...",
    "status": "running",
    "created_time": "2026-09-17T10:00:00Z"
  }
}

Completed Response

{
  "code": 200,
  "data": {
    "task_id": "task-unified-...",
    "status": "finished",
    "files": [
      {
        "file_url": "https://storage.vidgo.ai/generated/video.mp4",
        "file_type": "video"
      }
    ],
    "created_time": "2026-08-22T10:00:00Z",
    "progress": 100,
    "error_message": null
  }
}

Complete Runnable Example

Expand to inspect complete code including status checks, task_id validation, polling, and timeout boundaries.

Complete Runnable Example

set -euo pipefail
: "${VIDGO_API_KEY:?Set VIDGO_API_KEY in your environment}"

REQUEST_BODY=$(cat <<'JSON'
{
  "model": "alibaba/happyhorse-1.0/reference-to-video",
  "input": {
    "prompt": "character1 stands at the workshop stage from character3 and brings the knight marionette character2 to life, making it bow and raise its wooden sword while warm lamp light flickers, cinematic slow push in, no text, no logos, no watermark, no promotional marks",
    "duration": 5,
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "reference_image_urls": [
      "https://cdn.vidgo.ai/apis/models/alibaba/happyhorse-1.0/reference-to-video/v1/01/input-01.png",
      "https://cdn.vidgo.ai/apis/models/alibaba/happyhorse-1.0/reference-to-video/v1/01/input-02.png",
      "https://cdn.vidgo.ai/apis/models/alibaba/happyhorse-1.0/reference-to-video/v1/01/input-03.png"
    ]
  }
}
JSON
)

SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  --request POST \
  --url "https://api.vidgo.ai/api/generate/submit" \
  --header "Authorization: Bearer $VIDGO_API_KEY" \
  --header "Content-Type: application/json" \
  --data "$REQUEST_BODY")

TASK_ID=$(printf '%s' "$SUBMIT_RESPONSE" | jq -r '.data.task_id // .task_id // empty')
BUSINESS_CODE=$(printf '%s' "$SUBMIT_RESPONSE" | jq -r '.code // empty')
if [ "$BUSINESS_CODE" != "0" ] && [ "$BUSINESS_CODE" != "200" ]; then
  printf 'Submit failed:
%s
' "$SUBMIT_RESPONSE" >&2
  exit 1
fi
if [ -z "$TASK_ID" ]; then
  printf 'Submit response did not include task_id:
%s
' "$SUBMIT_RESPONSE" >&2
  exit 1
fi

START_TIME=$(date +%s)
POLL_DELAY=2
while true; do
  if [ $(( $(date +%s) - START_TIME )) -ge 600 ]; then
    printf 'Timed out after 600 seconds
' >&2
    exit 1
  fi
  STATUS_RESPONSE=$(curl --silent --show-error --fail-with-body \
    --url "https://api.vidgo.ai/api/generate/status/$TASK_ID" \
    --header "Authorization: Bearer $VIDGO_API_KEY")
  STATUS=$(printf '%s' "$STATUS_RESPONSE" | jq -r '.data.status // .status // empty')
  BUSINESS_CODE=$(printf '%s' "$STATUS_RESPONSE" | jq -r '.code // empty')
  if [ "$BUSINESS_CODE" != "0" ] && [ "$BUSINESS_CODE" != "200" ]; then
    printf 'Status request failed:
%s
' "$STATUS_RESPONSE" >&2
    exit 1
  fi

  case "$STATUS" in
    finished)
      printf '%s' "$STATUS_RESPONSE" | jq -r '(.data.files // .files // [])[]?.file_url'
      break
      ;;
    failed)
      printf '%s' "$STATUS_RESPONSE" | jq -r '.data.error_message // .error_message // "Generation failed"' >&2
      exit 1
      ;;
    not_started|running)
      sleep "$POLL_DELAY"
      if [ "$POLL_DELAY" -lt 10 ]; then POLL_DELAY=$((POLL_DELAY + 1)); fi
      ;;
    *)
      printf 'Unexpected task status: %s
' "$STATUS" >&2
      exit 1
      ;;
  esac
done

Input Parameters

Available request parameters, data types, and default values. The top-level model field is also required.

Field	Type	Required	Default	Description
reference_image_urls	array	Yes	—	String array. Contains 1–9 public image URLs as reference assets.
prompt	string	Yes	—	Required, nonblank, and at most 2,500 characters. Describe referenced subjects, actions, and camera movement; no specific character markers are required.
resolution	string	No	1080p	String. Output resolution. Supports 720p and 1080p.
duration	integer	No	5	Integer. Output duration from 3 to 15 seconds.
aspect_ratio	string	No	16:9	String. Output aspect ratio. Supports 16:9, 9:16, 1:1, 4:3, and 3:4.
seed	integer	No	—	Integer. 0 to 2147483647 for reproducible generation foundations.
enable_safety_checker	boolean	No	—	Boolean. Enables content safety moderation for inputs and outputs.

Response Fields

Task submission returns a task_id; status queries yield lifecycle progress and video assets.

Field	Type	Description
code	integer	Business response code, 200 on success.
data.task_id	string	Unique task identifier used to track and poll progress.
data.status	string	Lifecycle state: not_started, running, finished, or failed.
data.progress	integer	Generation completion percentage (0–100).
data.files[].file_url	string	Public URL of the generated video asset.
data.files[].file_type	string	File type string, e.g., video.
data.error_message	string \| null	Failure details when status equals failed.

Task Lifecycle

Continue polling while in not_started or running. Conclude when finished or failed is reached.

not_started
Task is accepted in the queue and awaiting execution.
running
Generation is actively in progress. Continue polling.
finished
Task completed successfully. Read video from data.files[].file_url.
failed
Generation failed. Read data.error_message and stop polling.

Polling & Error Handling

AuthenticationIf HTTP 401 is returned, verify the Bearer API key in the Authorization header.
ValidationIf HTTP 400 is returned, verify required parameters, valid value ranges, and available credits.
Network & TimeoutIf status polling encounters a network timeout, retain the task_id and retry the query.
Polling FrequencyPoll every 2 seconds initially, gradually backing off for longer generations.
Terminal StatesOnly continue polling on not_started or running. Halt on finished or failed.
Callback SupportProvide callback_url in the request payload to receive final task payloads via webhook.

Endpoint Specifications

Specification	Value	Details
Input Mode	1–9 Reference Images + Bound Prompt	Supply reference images and reference them using token names in prompt.
Reference Quantity	1 to 9 Image URLs	Passed as elements in the reference_image_urls array.
Token Syntax	Natural-language descriptions; character markers optional	Corresponds to reference_image_urls array index order.
Output Format	MP4 Video	Asynchronous response returns task_id; final result provides downloadable video URL.
Resolution	720p / 1080p	Default preselected to 1080p.
Duration	3–15 seconds	Default preselected to 5 seconds.
Aspect Ratio	16:9 / 9:16 / 1:1 / 4:3 / 3:4	Default preselected to 16:9.
Billing	Per-second rate	720p at 16 credits/s, 1080p at 32 credits/s.

View Happy Horse 1.0 Reference to Video API docs

Happy Horse 1.0 Reference to Video

Happy Horse 1.0 Reference to Video focuses on multi-image feature transfer and cross-shot narrative consistency. Users provide 1–9 reference images and describe referenced subjects in natural language; character1 and character2 markers are optional. Free from the fixed perspective constraint of a single starting keyframe, this endpoint allows you to introduce designated characters, hero props, and visual styles into entirely new camera setups and story worlds.

Key Capabilities & Advantages

Flexible 1–9 Multi-Subject Image InputsIngest multi-angle character portraits, character-plus-prop pairings, or aesthetic style references to establish deep visual context.
Describe each referenced subjectDescribe each subject’s appearance, actions, and relative position without requiring specific character markers.
Cross-Shot Likeness & Aesthetic ContinuityExtracts deep latent feature embeddings to preserve facial bone structure, hairstyle, and attire through camera sweeps.
Free Camera Blocking Unconstrained by First FramesLiberated from single-frame spatial anchors, directing fresh compositions, dynamic crane angles, and orbital moves freely.
1080p Cinematic Texture & Nuanced PerformanceRenders intricate fabric textures, subtle facial expressions, and environmental lighting with exceptional fidelity.
5 Aspect Ratios & 3–15s Motion PacingConfigure standard aspect ratios (16:9, 9:16, 1:1, 4:3, 3:4) alongside continuous motion durations up to 15 seconds.

Parameters

Parameter	Requirement	Description
reference_image_urls	Required	String array. Provide 1–9 public image URLs as reference assets.
prompt	Required	Required, nonblank, and at most 2,500 characters. Describe referenced subjects, actions, and camera movement; no specific character markers are required.
resolution	Optional	String. Output resolution. Choose between 720p and 1080p. The Playground preselects 1080p. Default`1080p720p`
duration	Optional	Integer. Output duration from 3 to 15 seconds. The Playground preselects 5 seconds. Default`5346789101112131415`
aspect_ratio	Optional	String. Output aspect ratio. The Playground preselects 16:9. Default`16:99:161:14:33:4`
seed	Optional	Integer. 0 to 2147483647 for reproducible generation foundations.
enable_safety_checker	Optional	Boolean. Enables content safety moderation for inputs and outputs.

How to Call Happy Horse 1.0 Reference to Video API

Step 1: Assemble Reference ImagesUpload 1–9 high-clarity images of your characters, wardrobe, or signature props to public URLs.
Step 2: Compose Token-Bound PromptsDescribe each referenced subject, its actions, and relative position. character1 and character2 can be used in examples, but are not required prompt syntax.
Step 3: Submit Request & Retrieve VideoCall POST /api/generate/submit, poll until finished, and access the final rendered MP4 asset.

Happy Horse 1.0 Pricing Overview

Billed per second based on resolution and duration. 720p is 16 credits/s ($0.08/s), and 1080p is 32 credits/s ($0.16/s). Credits are deducted on submission and refunded if the task fails.

Usage	Rate	Details
720p	16 credits/s	Fast character blocking and motion testing; a standard 5s generation costs 80 credits.
1080p	32 credits/s	High-fidelity production; a standard 5s generation costs 160 credits.

Best Use Cases

Virtual IP & Serialized StorytellingMaintain facial and stylistic likeness of original characters across multiple scenes, dialogues, and plot points.
Multi-Character Dramatic InteractionsSupply references for two distinct characters, choreographing seamless two-shots and interactions without identity blending.
Fashion Apparel & Prop ShowcasesProvide model headshots alongside specific fashion items to render high-fidelity virtual runway walks and lifestyle videos.
Game Character & Concept Art AnimationTransform 2D character sheets and weapon concept art into high-impact cinematic battle choreography.
Brand Mascot Cross-Campaign ProductionAnchor corporate mascots and brand ambassadors consistently across seasonal campaign creatives.
Stylized Animation & Visual AnthologiesExtract distinct artistic aesthetics from reference artworks to generate visually cohesive animated short films.

Pro Tips

Describe each referenced subject, its actions, and relative position. character1 and character2 can be used in examples, but are not required prompt syntax.
Include multiple angles (e.g., front and 3/4 profile) of key characters to reinforce 3D rotational consistency
Clearly distinguish between constant character features and shot-specific actions in your written prompt
Render in 1080p resolution to preserve delicate clothing embroidery, skin textures, and eye reflections from the source images
Describe each referenced subject, its actions, and relative position. character1 and character2 can be used in examples, but are not required prompt syntax.
Fix the random seed to isolate and evaluate choreography adjustments while keeping the character baseline stable

Usage Notes

Specify model as alibaba/happyhorse-1.0/reference-to-video in the top-level request body.
The reference_image_urls field accepts 1 to 9 image URLs as the reference gallery.
prompt is required; character1, character2, or other specific markers are not required.
Duration supports 3 to 15 integer seconds; resolution supports 720p or 1080p.

Related Models

Gemini Omni 1.1 Flash Text-to-Video preview

Gemini Omni 1.1 Flash Text-to-VideoGoogle Gemini Omni 1.1 Flash video model with native audio, text-to-video, first/last-frame image-to-video, reference-image video, and 3–10 second video edit at 360p to 4K.

Gemini Omni 1.1 Flash Image-to-Video preview

Gemini Omni 1.1 Flash Image-to-VideoGoogle Gemini Omni 1.1 Flash video model with native audio, text-to-video, first/last-frame image-to-video, reference-image video, and 3–10 second video edit at 360p to 4K.

Gemini Omni 1.1 Flash Reference-to-Video preview

Gemini Omni 1.1 Flash Reference-to-VideoGoogle Gemini Omni 1.1 Flash video model with native audio, text-to-video, first/last-frame image-to-video, reference-image video, and 3–10 second video edit at 360p to 4K.

Gemini Omni 1.1 Flash Video Edit preview

Gemini Omni 1.1 Flash Video EditGoogle Gemini Omni 1.1 Flash video model with native audio, text-to-video, first/last-frame image-to-video, reference-image video, and 3–10 second video edit at 360p to 4K.

MiniMax H3 Max Turbo Text to Video preview

MiniMax H3 Max Turbo Text to VideoMiniMax H3 Max Turbo Text to Video turns text into coherent 5–15 second videos with synchronized native stereo audio and fast generation. It follows physical motion while rendering subtle changes in light and shadow.

MiniMax H3 Max Turbo Image to Video preview

MiniMax H3 Max Turbo Image to VideoMiniMax H3 Max Turbo Text to Video turns text into coherent 5–15 second videos with synchronized native stereo audio and fast generation. It follows physical motion while rendering subtle changes in light and shadow.

MiniMax H3 Max Text to VideoMiniMax H3 Max Text to Video turns text prompts into cinematic video with native stereo audio, faster-than-real-time generation, and precise instruction following. It renders complex camera work and physical motion with fine detail across multiple resolutions and common aspect ratios.

MiniMax H3 Max Image to VideoMiniMax H3 Max Text to Video turns text prompts into cinematic video with native stereo audio, faster-than-real-time generation, and precise instruction following. It renders complex camera work and physical motion with fine detail across multiple resolutions and common aspect ratios.

MiniMax H3 Max Reference to Video preview

MiniMax H3 Max Reference to VideoMiniMax H3 Max Text to Video turns text prompts into cinematic video with native stereo audio, faster-than-real-time generation, and precise instruction following. It renders complex camera work and physical motion with fine detail across multiple resolutions and common aspect ratios.

Wan 3.0 Prime Text-to-VideoAlibaba Wan 3.0 Prime video model with text-to-video, image-to-video, and reference-to-video workflows at 480p, 720p, or 1080p for 2 to 30 seconds with optional synchronized audio.

Wan 3.0 Prime Image-to-VideoAlibaba Wan 3.0 Prime video model with text-to-video, image-to-video, and reference-to-video workflows at 480p, 720p, or 1080p for 2 to 30 seconds with optional synchronized audio.

Wan 3.0 Prime Reference-to-Video preview

Wan 3.0 Prime Reference-to-VideoAlibaba Wan 3.0 Prime video model with text-to-video, image-to-video, and reference-to-video workflows at 480p, 720p, or 1080p for 2 to 30 seconds with optional synchronized audio.

Wan 3.0 Text-to-VideoAlibaba Tongyi Lab's Wan 3.0 multimodal video model with separate text-to-video, first/last-frame image-to-video, and reference-to-video workflows at 480p, 720p, or 1080p for 2 to 30 seconds.

Wan 3.0 Image-to-VideoAlibaba Tongyi Lab's Wan 3.0 multimodal video model with separate text-to-video, first/last-frame image-to-video, and reference-to-video workflows at 480p, 720p, or 1080p for 2 to 30 seconds.

Wan 3.0 Reference-to-VideoAlibaba Tongyi Lab's Wan 3.0 multimodal video model with separate text-to-video, first/last-frame image-to-video, and reference-to-video workflows at 480p, 720p, or 1080p for 2 to 30 seconds.

FLUX 3 Text to VideoBlack Forest Labs FLUX 3 video model with text-to-video, image-to-video, first-last-frame, extend-video, and keyframes workflows at 720p or 1080p for 5 to 20 seconds, with optional native audio.

Happy Horse 1.0 Reference to Video API Frequently Asked Questions

What is the Happy Horse 1.0 Reference to Video API?

Happy Horse 1.0 Reference to Video is an Alibaba model for video generation guided by reference images. It ingests 1–9 reference images alongside structured prompt descriptions to generate 3–15s cinematic videos in 720p or 1080p, delivering exceptional entity binding and multi-subject identity consistency. Built on multimodal cross-attention and feature disentanglement architectures, it preserves facial likeness, clothing, and props while choreographing fresh camera angles and narrative interactions. You can call it programmatically or try it from the playground above.

How many reference images does Happy Horse 1.0 Reference to Video support?

It supports between 1 and 9 reference image URLs in reference_image_urls. You can combine multiple facial angles, specific costume details, or unique key props to construct a robust visual identity anchor.

How do prompts reference images in Happy Horse 1.0 Reference to Video?

Describe each referenced subject, its actions, and relative position. character1 and character2 can be used in examples, but are not required prompt syntax.

Can Happy Horse 1.0 Reference to Video handle multi-character scenes?

Yes. Provide reference images for the characters and describe their appearance, actions, and relative positions; no specific character markers are required.

Is Happy Horse 1.0 Reference to Video constrained by a starting frame?

No. Unlike image-to-video keyframe workflows, this endpoint extracts latent identity embeddings and synthesizes entirely fresh camera angles, perspectives, and movement unconstrained by an opening still frame.

Does Happy Horse 1.0 Reference to Video support 1080p output?

Yes. You can switch between 720p and 1080p via the resolution parameter. The 1080p setting accurately preserves intricate cloth textures, facial features, and lighting subtleties from the reference gallery.

When should you choose Happy Horse 1.0 Reference to Video over Text to Video?

Choose Reference to Video whenever you must maintain consistent character identity, specific wardrobe, or distinct artistic style across scenes. If your concept requires purely spontaneous generation from text without recurring subjects, choose Text to Video.