Alibaba Wan 3.0 Image To Video API Documentation

Alibaba Wan 3.0 Image To Video API Documentation

Playground

Wan 3.0 Image to Video animates a first-frame image into a cinematic video, with optional last-frame guidance, flexible 2-30 second duration, aspect ratio control, optional audio, and deep-thinking controls for high-quality motion and scene continuity. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

Features

Wan 3.0 Image-to-Video animates a first-frame image into a coherent video with optional last-frame guidance, audio generation, and deep-thinking mode. It preserves the input image’s subject and composition while adding prompt-guided motion, camera movement, and scene progression.

Parameters

How to Use

1. Upload the first-frame image — Provide the image that should guide the subject, composition, and starting frame.
2. Add last-frame guidance optional — Use last_image when you want to control the final frame or ending direction.
3. Write your prompt — Describe the motion, action, camera movement, lighting, mood, and scene progression.
4. Choose resolution — Use 480p for lower-cost drafts, 720p for balanced output, or 1080p for higher quality.
5. Set duration — Choose a duration from 2 to 30 seconds.
6. Configure audio optional — Keep enable_audio enabled when audio is needed.
7. Enable thinking mode optional — Use thinking_mode for more complex motion or composition instructions.
8. Submit — Generate the final image-to-video output.

Pricing

Pricing is based on output resolution and billed duration.

Billed duration is rounded up to the next whole second and clamped to the 2–30s range.

Example Costs

Best Use Cases

• Image animation — Animate product, portrait, lifestyle, or concept images into coherent video clips.
• First-and-last-frame control — Use image and last_image to guide both the beginning and ending of the video.
• Product and marketing videos — Turn product images into short promotional clips.
• Social media content — Create vertical, square, landscape, or widescreen videos from still images.
• Creative prototyping — Test motion, camera direction, and visual style from a fixed image.

Pro Tips

• Use a clear, high-quality first-frame image for better subject preservation.
• Use last_image when the final pose, composition, or ending frame matters.
• Describe motion clearly, including what moves, how the camera moves, and how the scene develops.
• Use 480p for quick drafts and 1080p for higher-quality output.
• Use shorter durations for iteration, then increase duration once the motion direction is confirmed.
• Enable thinking_mode for complex prompts with multiple movement or composition requirements.
• Set a fixed seed when you want more reproducible results.

Related Models

• Wan 3.0 Text-to-Video — Generate coherent cinematic videos from natural-language prompts.
• Wan 3.0 Image-to-Video — Animate a first-frame image into a coherent video with optional last-frame guidance.
• Wan 3.0 Reference-to-Video — Generate videos using reference images, videos, or audio for multimodal guidance.

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",
  "aspect_ratio": "16:9",
  "duration": 5,
  "thinking_mode": false,
  "enable_audio": true
}
JSON
)

# 1. Submit the prediction.
SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  -X POST "https://api.wavespeed.ai/api/v3/alibaba/wan-3.0/image-to-video" \
  -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