Hunyuan Video I2V API Documentation

Hunyuan Video I2V API Documentation

Playground

Hunyuan i2v turns images and text prompts into high-quality videos, generating coherent short clips from descriptive inputs. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

Features

Hunyuan Video I2V is an image-to-video model that turns a single reference image into a short animated clip guided by a text prompt. Upload an image to lock in subject, composition, and style, then describe the action and camera behavior you want. The model is well-suited for cinematic motion, character-driven beats, and atmospheric scenes where you want the “still” to come alive with coherent movement.

Key capabilities

• Image-to-video generation from one reference image
• Prompt-driven motion: actions, expressions, environment changes, camera movement
• Stable composition anchored to the input image
• Good for cinematic, dramatic, and stylized shots
• Supports duration and inference-step controls for quality vs. speed tradeoffs
• Multiple output sizes (e.g., 1280×720)

Use cases

• Animate key art, posters, and character portraits into short clips
• Cinematic micro-stories: close-up → reveal, slow push-ins, mood-heavy scenes
• Atmosphere and VFX-style motion: rain, fog, embers, neon flicker, drifting particles
• Social content loops from a single still image
• Rapid previsualization for scenes before full video production

Pricing

Inputs

• image (required): reference image to anchor subject and style
• prompt (required): action + camera directions

Parameters

• duration: clip length in seconds
• num_inference_steps: sampling steps (higher often improves coherence/detail)
• seed: random seed (-1 for random; set for reproducible results)
• size: output resolution (e.g., 1280×720)

Prompting guide (I2V)

Write prompts like a director’s brief:

• Subject: who/what is on screen
• Action: what changes over time (gestures, expression, environment)
• Camera: push-in, pull-back, pan, tilt, handheld vs. locked-off
• Mood/lighting: candlelight, moonlight, neon, fog, rim light
• Motion constraints: “subtle movement”, “no shaky camera”, “smooth dolly”

Example prompts

• A pale vampire woman stands at a candlelit window, crimson eyes glowing. She slowly raises her hand and taps long nails against the glass. Her expression shifts from seductive to dangerous as bats flutter past outside. Slow cinematic push-in, soft candle flicker, subtle fog, smooth motion, dramatic lighting.

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'
{
  "image": "https://interactive-examples.mdn.mozilla.net/media/cc0-images/painted-hand-298-332.jpg",
  "num_inference_steps": 30,
  "duration": 5,
  "seed": -1,
  "size": "1280*720"
}
JSON
)

# 1. Submit the prediction.
SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  -X POST "https://api.wavespeed.ai/api/v3/wavespeed-ai/hunyuan-video/i2v" \
  -H "Authorization: Bearer ${WAVESPEED_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "${REQUEST_BODY}")

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
' >&2
  exit 1
fi
RESULT_URL=$(printf '%s' "${TASK}" | jq -r '.urls.get // empty')
if [ -z "${RESULT_URL}" ]; then RESULT_URL="https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result"; fi

# 2. Poll until the prediction finishes.
while true; do
  RESPONSE=$(curl --silent --show-error --fail-with-body \
    "${RESULT_URL}" \
    -H "Authorization: Bearer ${WAVESPEED_API_KEY}")
  RESULT=$(printf '%s' "${RESPONSE}" | jq 'if type == "object" and has("data") then .data else . end')
  STATUS=$(printf '%s' "${RESULT}" | jq -r '.status // empty')

  case "${STATUS}" in
    completed) printf '%s\n' "${RESULT}" | jq '.outputs'; break ;;
    failed|cancelled|timeout) printf '%s\n' "${RESULT}" | jq . >&2; exit 1 ;;
    created|processing) sleep 2 ;;
    *) printf 'Unexpected status: %s
' "${STATUS}" >&2; exit 1 ;;
  esac
done

Parameters

Task Submission Parameters

Request Parameters

Response Parameters

Result Request Parameters

Result Response Parameters