Alibaba Happyhorse 1.1 Image To Video API Documentation

Alibaba Happyhorse 1.1 Image To Video API Documentation

Playground

Alibaba HappyHorse 1.1 Image to Video animates a reference image into a cinematic 720P or 1080P video, with optional text prompt guidance, smooth camera movement, and expressive, stable motion. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

Features

Alibaba Happy Horse 1.1 Image-to-Video animates a reference image into a cinematic video with optional text guidance for motion, camera movement, and scene direction. It supports 480p, 720p and 1080p output, while preserving the reference image’s subject, composition, and visual style.

Why Choose This?

• Image-faithful generation
  Preserves the reference image’s subject, composition, and style while adding motion.

• Optional prompt guidance
  Describe the camera movement, mood, action, and scene development in plain language.

• Cinematic motion
  Generate smooth, expressive motion with stable subject preservation.

• Flexible resolution options
  Choose 480p for the lowest cost, 720p for standard generation or 1080p for higher-resolution output.

• Production-ready API
  Use REST inference for image-to-video generation workflows.

Parameters

How to Use

1. Upload image — Provide a first-frame image URL.
2. Add prompt guidance (optional) — Describe the desired motion, camera behavior, mood, or action.
3. Select resolution — Choose 480p, 720p or 1080p.
4. Set duration — Choose a duration from 3 to 15 seconds.
5. Set seed (optional) — Use a fixed seed for reproducible results.
6. Generate — Create the image-to-video output.

Pricing

• Total price: per-second rate × duration

Best Use Cases

• Image-to-video animation — Animate a reference image into a short video.
• Cinematic motion generation — Add smooth camera movement and scene motion to a still image.
• Character and subject animation — Preserve the main subject while generating natural motion.
• Creative video previews — Create short visual clips from concept images or storyboards.
• Social media content — Generate short-form video assets from still images.

Pro Tips

• Use a clear first-frame image with the main subject visible.
• Keep the prompt focused on motion, camera behavior, and scene development.
• Use 480p for the lowest cost and 720p for standard generation.
• Use 1080p when higher-resolution output is needed.
• Use a fixed seed when you want more reproducible results.
• Make sure the input image matches the desired output composition.

Related Models

• Alibaba Happy Horse 1.1 Text-to-Video — Generate video directly from text.

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",
  "image": "https://interactive-examples.mdn.mozilla.net/media/cc0-images/painted-hand-298-332.jpg",
  "resolution": "720p",
  "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/image-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