Alibaba Wan 3.0 Reference To Video API Documentation

Alibaba Wan 3.0 Reference To Video API Documentation

Playground

Wan 3.0 Reference to Video creates coherent videos from prompts and multimodal references, including images, videos, and audio, with flexible 2-30 second duration and aspect ratio control for subject consistency, motion guidance, timing control, and scene continuity. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

Features

Wan 3.0 Reference-to-Video combines reference images, videos, and audio with a prompt to create coherent video scenes. It supports multimodal reference guidance for character consistency, object control, motion direction, audio style, and scene composition.

Parameters

At least one of reference_images, reference_videos, or reference_audios is required.

How to Use

1. Add reference media — Provide reference images, videos, audio, or a combination of them.
2. Write your prompt — Describe the target scene, action, camera movement, lighting, style, and how the references should be used.
3. Choose resolution — Use 480p for lower-cost drafts, 720p for balanced output, or 1080p for higher quality.
4. Set aspect ratio — Select the output format that matches your target platform or creative direction.
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 prompt expansion optional — Use enable_prompt_expansion for complex prompts with multiple reference requirements.
8. Submit — Generate the final reference-guided video.

Pricing

Pricing uses normalized reference-video duration plus output duration. Each reference video is padded to at least 1 second, capped at 15 seconds, and the combined input is capped at 15 seconds and rounded up to a whole second for billing.

Example: 5 seconds of normalized input plus 5 seconds of output costs $0.50 at 480p, $1.00 at 720p, or $2.00 at 1080p.

Best Use Cases

• Character-consistent storytelling — Generate scenes guided by character, face, outfit, or style references.
• Multi-reference video generation — Combine people, objects, environments, motion, and audio references in one workflow.
• Product and brand videos — Use reference assets to preserve product appearance or campaign style.
• Audio-guided scenes — Use reference audio to guide mood, rhythm, ambience, or sound direction.
• Social media content — Create short-form videos from multimodal references.
• Creative prototyping — Test different scene directions while keeping reference-guided consistency.

Pro Tips

• Use clear reference images when identity, product detail, or visual style matters.
• Use reference videos when motion, pacing, gesture, or camera behavior matters.
• Use reference audio when ambience, rhythm, voice style, or soundtrack direction matters.
• Explain how each reference should influence the final video in the prompt.
• Use 480p for quick drafts and 1080p for higher-quality output.
• Enable enable_prompt_expansion for prompts that combine multiple references or detailed scene 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",
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "duration": 5,
  "enable_prompt_expansion": 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/reference-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="https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result"

# 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|deleted) printf '%s\n' "${RESULT}" | jq . >&2; exit 1 ;;
    *) sleep 2 ;;
  esac
done

Parameters

Task Submission Parameters

Request Parameters

Response Parameters

Result Request Parameters

Result Response Parameters