Wan3.0

Introduction

Wan 3.0 accepts video and audio as reference inputs, alongside images. Reference videos carry a subject's identity, motion, and character across a new scene. Reference audios drive the video with a specific soundtrack or sonic character. Both can be combined in the same call, together with reference images, to compose a single request across all four modalities Wan reads.

The example below is the simplest video-reference case. A short source clip of a fitness instructor demonstrating a squat is passed as referenceVideos. The output places the same instructor in a completely different setting (an outdoor park) doing a different exercise (a walking lunge), with her identity and controlled coaching style carried across.

Her identity carries through the two clips (same instructor, same outfit, same coaching demeanour), but the setting, the exercise, and the audio are all generated fresh from the prompt. Video references pin who and how. The prompt describes what happens next.

This guide covers the three reference-input modalities Wan 3.0 accepts, referenceVideos for subject and motion carry, referenceAudios for audio-driven generation, and the multi-modal combination where image, video, and audio references all compose into one call.

Request shape

Reference inputs are attached under inputs. Each accepts a UUID or a URL. Reference images accept data URIs and Base64 too, but reference videos and audios must be UUIDs or URLs. Dimensions come from the input aspect, so use resolution to pick the tier rather than width/height.

import { createClient } from '@runware/sdk'

const client = await createClient({ apiKey: process.env.RUNWARE_API_KEY })
await client.connect()

const [result] = await client.run({
  model: 'alibaba:wan@3.0',
  positivePrompt: 'The fitness instructor from the reference video is now outdoors in a bright morning park with soft grass underfoot, wearing the same fitted black tank top and grey leggings. She demonstrates a controlled walking lunge, stepping forward with her right leg into a deep lunge, hold, then push back up. She glances up briefly and says naturally: "Good form matters more than reps. Slow the movement down, feel the muscle work." Camera locked at chest height showing her full body. Warm morning light, park visible softly behind her. Audio: her voice clean and warm, controlled exhale on each rep, birdsong in the background, distant park ambience. No music, no on-screen text, no subtitles.',
  inputs: {
    referenceVideos: [
      'https://vm.runware.ai/video/os/a14d18/ws/2/vi/aabb1122-3344-5566-7788-99aabbccddee.mp4'
    ]
  },
  resolution: '1080p',
  duration: 8
})

import asyncio
import os

from runware import Runware


async def main():
    async with Runware(api_key=os.environ["RUNWARE_API_KEY"]) as client:
        results = await client.run({
            "model": "alibaba:wan@3.0",
            "positivePrompt": "The fitness instructor from the reference video is now outdoors in a bright morning park with soft grass underfoot, wearing the same fitted black tank top and grey leggings. She demonstrates a controlled walking lunge, stepping forward with her right leg into a deep lunge, hold, then push back up. She glances up briefly and says naturally: \"Good form matters more than reps. Slow the movement down, feel the muscle work.\" Camera locked at chest height showing her full body. Warm morning light, park visible softly behind her. Audio: her voice clean and warm, controlled exhale on each rep, birdsong in the background, distant park ambience. No music, no on-screen text, no subtitles.",
            "inputs": {
                "referenceVideos": [
                    "https://vm.runware.ai/video/os/a14d18/ws/2/vi/aabb1122-3344-5566-7788-99aabbccddee.mp4"
                ]
            },
            "resolution": "1080p",
            "duration": 8
        })


asyncio.run(main())

curl https://api.runware.ai/v1 \
  -H "Authorization: Bearer $RUNWARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "taskType": "videoInference",
      "taskUUID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "model": "alibaba:wan@3.0",
      "positivePrompt": "The fitness instructor from the reference video is now outdoors in a bright morning park with soft grass underfoot, wearing the same fitted black tank top and grey leggings. She demonstrates a controlled walking lunge, stepping forward with her right leg into a deep lunge, hold, then push back up. She glances up briefly and says naturally: \"Good form matters more than reps. Slow the movement down, feel the muscle work.\" Camera locked at chest height showing her full body. Warm morning light, park visible softly behind her. Audio: her voice clean and warm, controlled exhale on each rep, birdsong in the background, distant park ambience. No music, no on-screen text, no subtitles.",
      "inputs": {
        "referenceVideos": [
          "https://vm.runware.ai/video/os/a14d18/ws/2/vi/aabb1122-3344-5566-7788-99aabbccddee.mp4"
        ]
      },
      "resolution": "1080p",
      "duration": 8
    }
  ]'

runware run alibaba:wan@3.0 \
  positivePrompt="The fitness instructor from the reference video is now outdoors in a bright morning park with soft grass underfoot, wearing the same fitted black tank top and grey leggings. She demonstrates a controlled walking lunge, stepping forward with her right leg into a deep lunge, hold, then push back up. She glances up briefly and says naturally: \"Good form matters more than reps. Slow the movement down, feel the muscle work.\" Camera locked at chest height showing her full body. Warm morning light, park visible softly behind her. Audio: her voice clean and warm, controlled exhale on each rep, birdsong in the background, distant park ambience. No music, no on-screen text, no subtitles." \
  inputs.referenceVideos.0=https://vm.runware.ai/video/os/a14d18/ws/2/vi/aabb1122-3344-5566-7788-99aabbccddee.mp4 \
  resolution=1080p \
  duration=8

{
  "taskType": "videoInference",
  "taskUUID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "model": "alibaba:wan@3.0",
  "positivePrompt": "The fitness instructor from the reference video is now outdoors in a bright morning park with soft grass underfoot, wearing the same fitted black tank top and grey leggings. She demonstrates a controlled walking lunge, stepping forward with her right leg into a deep lunge, hold, then push back up. She glances up briefly and says naturally: \"Good form matters more than reps. Slow the movement down, feel the muscle work.\" Camera locked at chest height showing her full body. Warm morning light, park visible softly behind her. Audio: her voice clean and warm, controlled exhale on each rep, birdsong in the background, distant park ambience. No music, no on-screen text, no subtitles.",
  "inputs": {
    "referenceVideos": [
      "https://vm.runware.ai/video/os/a14d18/ws/2/vi/aabb1122-3344-5566-7788-99aabbccddee.mp4"
    ]
  },
  "resolution": "1080p",
  "duration": 8
}

[
  {
    "taskType": "videoInference",
    "taskUUID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "videoUUID": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "videoURL": "https://vm.runware.ai/video/os/a14d18/ws/2/vi/b2c3d4e5-f6a7-8901-bcde-f12345678901.mp4"
  }
]

Reference inputs are mutually exclusive with frameImages but freely combinable with each other. A single call can attach referenceImages, referenceVideos, and referenceAudios all at once. See the last section for the combined multi-modal pattern.

Reference videos for subject and motion carry

referenceVideos uses your source clip for identity and motion character. The reference itself never appears in the output. Wan 3.0 reads the video to understand who the subject is, how they move, and what their coaching or presentation style looks like, then generates a new clip in the scene the prompt describes.

The hero example above is the canonical use. The source video was 5 seconds of the instructor demonstrating one exercise. Wan 3.0 carried her identity (specific woman, specific outfit) and her coaching demeanour (controlled form, deliberate movements) into a new setting doing a different exercise entirely. That's stronger than a still image reference would give, because motion signature and micro-expressions inform the model's read of who this person is.

Reach for referenceVideos when the subject's motion or behaviour matters as much as their appearance. Recurring fitness instructors, brand mascots that move a specific way, spokespeople whose delivery style is part of their identity, characters across an episodic series. Anything where you want the new scene to read as "same person doing something different" rather than "a similar-looking person doing something different."

The array accepts up to 5 reference videos. Multiple videos of the same subject give a stronger identity signal, and multiple videos of different subjects let you compose a scene where they interact.

Other content types that map well to single-subject video reference:

• Character consistency across episodic content (same character across multiple episodes or scenes)
• Spokesperson libraries where one core recording is reused across many contexts and campaigns
• Product-demo carrying, with the same product handled and demonstrated across different settings
• Motion capture, from a workout instructor's technique carried into different exercises to a dancer's choreography carried into different environments
• Brand-mascot animations that place the same mascot into new scenarios
• Creator content at scale, with one recorded creator across many personalised video variations

Multiple video references in one scene

Passing more than one video reference asks Wan 3.0 to compose a scene that includes elements from each. The most common use is bringing two characters together in a new scene from separate solo source clips.

The output combined both references into a podcast-studio scene. She kept her tank top and coaching demeanour. He kept his navy sweater and thoughtful gesture. Wan 3.0 built the shared space (the studio, the table, the microphones) fresh and lip-synced each speaker's line to the appropriate face.

Multi-video reference is the pattern for collab content across a series, joint testimonials, character interactions, and any scene that composes multiple subjects that were each captured separately.

Other content types that map well to multi-subject video reference:

• Interview or podcast scenes composed from separate recordings
• Duet or collab creator content (two creators from separate uploads, together in a new scene)
• Multi-person testimonials or customer stories
• Team or family group content assembled from individual clips
• Character-interaction scenes where each character was recorded separately
• Personalised celebrity or spokesperson pairings for campaigns

Reference audios for audio-driven video

referenceAudios uses your source audio as a driver for what the video does. The audio becomes the soundtrack, and the visuals are generated to match it in rhythm and mood. The array accepts up to 5 audio inputs.

The reference audio was a 15-second warm ambient electronic instrumental with a soft rhythmic pulse. The output rendered a dance visual that lands the pivots and arm extensions on the underlying beat. The audio the reader hears is the reference audio itself, threaded through as the soundtrack, with the dancer's breath and footfalls layered on top.

Reach for referenceAudios when the audio is the anchor of the piece, not a supplement to it. Music videos where the choreography has to sync to a specific track. Lip-sync content where a specific voice has to drive the visible speaker. Sound-first pieces where the soundtrack existed before the video and the visuals need to serve it.

For a specific voice reference (a founder's voiceover, a customer testimonial audio, a narrator track), the pattern is the same: attach the audio, describe the visible speaker and setting in the prompt, and Wan 3.0 lip-syncs the visible subject to the reference audio's delivery.

Other content types that map well to audio-driven video:

• Music videos synced to a specific track
• Voice-driven visual companions (a podcast episode → animated visual companion for social distribution)
• Lip-sync content where a specific voice drives the visible speaker (existing testimonial audio → new visible spokesperson)
• Sound-first branded content where the soundtrack existed before the video and the visuals need to serve it
• Multilingual dubbing pipelines (audio recorded in a new language → matching new video generated per market)
• Audio-book or narrated-content video versions

Combining reference types

referenceImages, referenceVideos, and referenceAudios can all be attached in one call. This is Wan 3.0's most distinctive input pattern: a scene composed from an image (a product), a video (a subject), and an audio (a soundtrack), all directed by a single prompt.

The clip below combines three references from earlier in the guide: the fitness instructor's video (subject identity), a product image of premium wireless headphones (a specific product to place in the scene), and the ambient music track (the soundtrack). The prompt describes the scene: the instructor warming up in a modern gym while wearing the headphones.

The output composed all three. Her identity came from the video reference, the exact headphones came from the image reference, the music underneath came from the audio reference, and the gym scene came from the prompt. Wan 3.0 read the four inputs (text, image, video, audio) as parallel directives and built the shot from them.

The pattern maps to branded video work that would otherwise need a live shoot: a spokesperson in a new environment demonstrating a specific product with a specific soundtrack. Personalised marketing pipelines can vary the image (different products), the video (different spokespeople), or the audio (different music beds) while keeping the other references and the prompt stable.

Other content types that map well to combined reference modalities:

• Personalised ad pipelines (vary the product image per audience, keep the spokesperson video and music stable)
• Branded story sequences (character video + brand-asset image + custom music bed)
• UGC-scale content (a creator's video reference + a product image + a soundtrack, composed at scale for many products)
• Localised marketing (spokesperson stays consistent, product image changes per market, audio dubbed into the local language)
• Long-form marketing videos where character, product, and soundtrack all need to hold consistently across a longer runtime
• Sponsor-integrated creator content (creator video + sponsor product image + sponsor jingle audio)

Input constraints

Wan 3.0 enforces a small envelope on each reference input:

• Reference videos. Up to 5 videos per call. Each video is 1 to 15 seconds and up to 100 MB. Minimum 240 × 240 pixels, aspect ratio between 8:1 and 1:8. The output duration plus the reference video duration combined cannot exceed 30 seconds. Longer or larger files fail validation.
• Reference audios. Up to 5 audio clips per call. Each is 1 to 15 seconds and up to 15 MB.
• Reference images. Up to 10 images per call. Minimum 240 × 240 pixels, aspect ratio between 8:1 and 1:8, up to 20 MB each.

Plan the output duration accordingly when working with long reference videos. A 15-second reference video leaves at most 15 seconds of output. A 5-second reference leaves the full 25 remaining.

Tips

1. Reach for referenceVideos when motion or behaviour matters. Video references carry gait, cadence, expression, and coaching or presentation style, not just appearance. For recurring characters, spokespeople, or brand mascots whose motion signature is part of their identity, video references beat image references.

2. Trim reference videos to their strongest identity signal. A 5-second clip of the subject clearly in frame reads more strongly than a 15-second clip where they're partly obscured. Cut to the moments that show them best.

3. Reference videos carry into a fresh scene. The reference itself is not shown in the output. If the source scene is part of what needs to appear, use frameImages with a still from the video instead.

4. Multiple video references compose subjects into one scene. Two separate solo clips can be combined into a shared scene where both subjects appear together, useful for collab content and multi-character interaction.

5. Use referenceAudios when the audio is the anchor. Music videos, audio-driven marketing pieces, and lip-sync content where a specific voice or track drives the visuals. Wan uses the reference audio as the output soundtrack.

6. Combining references composes a shot across modalities. Image (product), video (subject), and audio (soundtrack) can all be attached to a single call. The prompt directs how they compose. Personalised pipelines can vary one reference while holding the others stable.

7. Keep reference clips inside the envelope. Each reference video is capped at 15 seconds and 100 MB. Each reference audio is capped at 15 seconds and 15 MB. Reference images are capped at 20 MB. Files above the limits fail validation.

8. Plan output duration against reference-video duration. The two combined cap at 30 seconds. A 15-second reference video leaves at most 15 seconds of output. Shorten the reference or shorten the output as needed.

9. frameImages and reference inputs cannot share a call. If the deliverable needs a specific opening frame plus a subject from a reference video, generate the two shots separately and edit them together.