Alibaba Happyhorse 1.1 Reference To Video API Documentation

Alibaba Happyhorse 1.1 Reference To Video API Documentation

Playground

Alibaba HappyHorse 1.1 Reference to Video generates new video scenes from reference images, preserving character identity, visual style, and scene consistency. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

Features

Alibaba Happy Horse 1.1 Reference-to-Video generates new video scenes guided by one or more reference images, helping maintain consistent characters, styles, and visual identity across the output. It combines reference-image grounding with natural-language prompting to create cinematic videos in 480p, 720p or 1080p.

• Need to generate directly from text? Try Alibaba Happy Horse 1.1 Text-to-Video.
• Need to animate a single starting frame instead? Try Alibaba Happy Horse 1.1 Image-to-Video.

Why Choose This?

• Reference-guided consistency
  Use one or more reference images to preserve character identity, visual style, outfit details, and overall scene language.

• Prompt and image control
  Combine reference images with a text prompt to control the scene, action, mood, and camera behavior more precisely.

• Cinematic motion
  Generate smooth, expressive video motion while keeping important visual elements stable and recognizable.

• Flexible output settings
  Choose output resolution, aspect ratio, duration, and seed to match your creative and production needs.

• Production-ready API
  Access the model through a REST inference API for scalable integration into apps and workflows.

Parameters

How to Use

1. Upload your reference images — Provide 1–9 image URLs that define the character, style, or visual identity you want to preserve.
2. Write your prompt — Describe the target scene, action, camera behavior, lighting, and mood.
3. Choose resolution — Use 480p for the lowest cost, 720p for everyday iteration or 1080p for higher-resolution output.
4. Set aspect ratio — Choose the format that best fits your target platform or composition needs.
5. Set duration — Choose a clip length between 3 and 15 seconds.
6. Set a seed optional — Use a fixed seed for more reproducible generations.
7. Submit — Generate and download your video.

Example Prompt

A cinematic fashion scene with the same character walking through a softly lit modern city street at night, gentle camera tracking, subtle wind in the hair and clothing, elegant movement, realistic lighting, premium commercial style.

Pricing

• Total price: per-second rate × duration

Best Use Cases

• Character consistency across scenes — Keep the same person, outfit, or visual identity across multiple generated videos.
• Brand and campaign content — Maintain a stable look and style across ad creatives, promos, and commercial storytelling.
• Style-preserving video generation — Use reference images to anchor art direction, color palette, and visual tone.
• Narrative concepting — Generate new scenes based on known characters or environments for storyboarding and ideation.
• Social media and short-form content — Create visually consistent clips tailored to different platforms and aspect ratios.
• Creative prototyping — Explore motion and scene variations while preserving core reference details.

Pro Tips

• Use clear, high-quality reference images that strongly represent the character, outfit, or style you want to preserve.
• Include multiple reference images when consistency across facial features, costume details, or design elements is important.
• Be specific in your prompt about scene, action, camera motion, lighting, and mood.
• Use 480p for quick, low-cost drafts, then switch to 720p or 1080p for final output.
• Reuse the same seed when you want more reproducible outputs.
• Start with shorter durations to validate identity consistency and motion before generating longer clips.

Related Models

• Alibaba Happy Horse 1.1 Text-to-Video — Generate cinematic videos directly from natural-language prompts.
• Alibaba Happy Horse 1.1 Image-to-Video — Animate a single reference image into a cinematic video clip.

Authentication

For authentication details, please refer to the Authentication Guide.

API Endpoints

Submit Task & Query Result

set -euo pipefail

export WAVESPEED_API_KEY="your-api-key"

REQUEST_BODY=$(cat <<'JSON'
{
  "prompt": "A cinematic ocean wave at sunrise, highly detailed",
  "images": [
    "https://interactive-examples.mdn.mozilla.net/media/cc0-images/painted-hand-298-332.jpg"
  ],
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "duration": 5
}
JSON
)

# 1. Submit the prediction once. Never retry this request automatically:
# a retry after an unclear failure can create a second, billed task.
CHECK='The task may already exist. Check History or the predictions list before submitting again.'
if ! SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  --connect-timeout 10 --max-time 60 \
  -X POST "https://api.wavespeed.ai/api/v3/alibaba/happyhorse-1.1/reference-to-video" \
  -H "Authorization: Bearer ${WAVESPEED_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "${REQUEST_BODY}"); then
  printf 'Submit failed. %s\n' "${CHECK}" >&2
  exit 1
fi

TASK=$(printf '%s' "${SUBMIT_RESPONSE}" | jq 'if type == "object" and has("data") then .data else . end')
PREDICTION_ID=$(printf '%s' "${TASK}" | jq -r '.id // empty')
if [ -z "${PREDICTION_ID}" ]; then
  printf 'Submission response did not contain a prediction id. %s\n' "${CHECK}" >&2
  exit 1
fi
RESULT_URL="https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result"

# 2. Poll until the prediction reaches a final status.
BODY_FILE=$(mktemp)
trap 'rm -f "${BODY_FILE}"' EXIT
while true; do
  # Transient errors (429, 5xx) are retried, honoring Retry-After.
  HTTP_CODE=$(curl --silent --show-error --fail-with-body \
    --connect-timeout 10 --max-time 60 --retry 5 --retry-delay 2 \
    --output "${BODY_FILE}" --write-out '%{http_code}' \
    "${RESULT_URL}" \
    -H "Authorization: Bearer ${WAVESPEED_API_KEY}" || true)
  case "${HTTP_CODE}" in
    2??) ;;
    000|429|5??)  # dropped connection or temporary error: keep polling
      printf 'Task %s: HTTP %s, polling again in 10s\n' "${PREDICTION_ID}" "${HTTP_CODE}" >&2
      sleep 10; continue ;;
    *) printf 'Task %s: HTTP %s\n' "${PREDICTION_ID}" "${HTTP_CODE}" >&2
      cat "${BODY_FILE}" >&2; exit 1 ;;
  esac
  RESULT=$(jq 'if type == "object" and has("data") then .data else . end' "${BODY_FILE}")
  STATUS=$(printf '%s' "${RESULT}" | jq -r '.status // empty')

  case "${STATUS}" in
    completed) printf '%s\n' "${RESULT}" | jq '.outputs'; break ;;
    failed|cancelled|timeout|deleted)
      printf 'Task %s ended with status %s\n' "${PREDICTION_ID}" "${STATUS}" >&2
      printf '%s\n' "${RESULT}" | jq . >&2; exit 1 ;;
    *) sleep 2 ;;
  esac
done

Parameters

Task Submission Parameters

Request Parameters

Every model also accepts the global request options enable_sync_mode and enable_base64_output; see their pages for details.

Response Parameters

Result Request Parameters

Result Response Parameters