--- title: Video and audio references with Wan 3.0 — Wan3.0 | Runware Docs url: https://runware.ai/docs/models/alibaba-wan3-0/guides/video-and-audio-references description: "How to use video and audio references with Wan 3.0: carrying a subject across new scenes with referenceVideos, driving video from an audio source with referenceAudios, and combining multiple reference types in one call." --- ### [Introduction](https://runware.ai/docs/models/alibaba-wan3-0/guides/video-and-audio-references#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. [Watch video](https://runware.ai/docs/assets/hero.Cmp2D921.mp4) *Video output* > **Prompt**: 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. **Source video**: [Watch video](https://runware.ai/docs/assets/source-fitness-instructor.D5fL-LfM.mp4) > **Prompt**: A 5-second wide interior shot of a fitness instructor in her thirties in a modern home gym, wearing a fitted black tank top and grey leggings, demonstrating a controlled goblet squat with a small kettlebell held at her chest. She is standing centred in frame on a rubber gym floor, warm mixed daylight from a window on the left. Camera locked at chest height showing her full body. She goes down into a squat, holds briefly at the bottom, and returns to standing with controlled form. Audio: her controlled exhale on each rep, the quiet ambient tone of the gym, the soft thud of her feet planting. No music, no on-screen text, no subtitles. 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](https://runware.ai/docs/models/alibaba-wan3-0/guides/video-and-audio-references#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`. TypeScriptPythoncURLCLIJSON ```typescript 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 }) ``` ```python 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()) ``` ```bash 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 } ]' ``` ```bash 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 ``` ```json { "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 } ``` Response ```json [ { "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](https://runware.ai/docs/models/alibaba-wan3-0/guides/video-and-audio-references#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](https://runware.ai/docs/models/alibaba-wan3-0/guides/video-and-audio-references#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. [Watch video](https://runware.ai/docs/assets/output-multi-video.BtIkcxhT.mp4) *Output composing both references* > **Prompt**: The fitness instructor from the first reference video and the wellness coach from the second reference video are now together in a warm modern podcast studio, seated across from each other at a small round table with two microphones on stands between them. She wears her same fitted black tank top, he wears his same navy sweater. They are mid-conversation about training and recovery. She says naturally: "Consistency beats intensity." He nods and replies: "Every time." Camera locked at a slight three-quarter angle showing both of them. Warm mixed lighting, soft studio ambience. Audio: their voices clean and warm as they trade the lines, ambient studio tone, no music. No on-screen text, no subtitles. **Fitness instructor**: [Watch video](https://runware.ai/docs/assets/source-fitness-instructor.D5fL-LfM.mp4) > **Prompt**: A 5-second wide interior shot of a fitness instructor in her thirties in a modern home gym, wearing a fitted black tank top and grey leggings, demonstrating a controlled goblet squat with a small kettlebell held at her chest. She is standing centred in frame on a rubber gym floor, warm mixed daylight from a window on the left. Camera locked at chest height showing her full body. She goes down into a squat, holds briefly at the bottom, and returns to standing with controlled form. Audio: her controlled exhale on each rep, the quiet ambient tone of the gym, the soft thud of her feet planting. No music, no on-screen text, no subtitles. **Wellness coach**: [Watch video](https://runware.ai/docs/assets/source-collab-guest.z5wfMYiB.mp4) > **Prompt**: A 5-second wide interior shot of a wellness coach in his forties in a modern home office, wearing a plain navy sweater and dark jeans, seated at a warm walnut desk facing the camera. Behind him a floor-to-ceiling bookshelf softly out of focus. He gestures thoughtfully with his hand as he speaks, warm confident expression. Camera locked at chest height. Warm daylight from a window on the left. Audio: only his soft ambient breath and the quiet room tone, no spoken words. No music, no on-screen text, no subtitles. 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](https://runware.ai/docs/models/alibaba-wan3-0/guides/video-and-audio-references#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. [Watch video](https://runware.ai/docs/assets/output-audio-driven.DJ1Jy-4-.mp4) *Audio-driven video: contemporary dance synced to a reference music track* > **Prompt**: A 15-second wide interior shot of a contemporary dancer performing a solo in a warm sunlit dance studio with pale hardwood floors and a wall of tall windows behind her. She is a woman in her twenties in a fitted grey leotard, moving with fluid controlled motion through a sequence of arm extensions and pivots synced to the audio track. The camera stays locked at eye level with her centred in the frame, the sunlight streaming in from behind creating a soft rim on her silhouette. Audio: the reference audio track is the primary music bed underneath, her breath audible on each pivot, the soft slap of bare feet on the wooden floor between beats. No on-screen text. **Source audio**: [Listen to audio](https://runware.ai/docs/assets/source-music.Dqc-cYx4.mp3) > **Prompt**: A slow warm ambient electronic instrumental track with soft synth pads, a gentle rhythmic pulse at 80 BPM, and a subtle bass foundation. The mood is contemplative and open. 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](https://runware.ai/docs/models/alibaba-wan3-0/guides/video-and-audio-references#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. [Watch video](https://runware.ai/docs/assets/output-combined.CeS-0PtO.mp4) *Combined references: subject video + product image + music audio* > **Prompt**: The fitness instructor from the reference video, wearing the same fitted black tank top and grey leggings, is now in a modern gym warming up with the specific pair of matte-black wireless over-ear headphones from the reference image on her head. She stretches her arms overhead, rolls her shoulders, and starts a light warm-up jog in place. Camera locked at chest height in a wide mid-shot. Warm modern gym lighting. Audio: the reference audio track underneath as a soft music bed, her controlled breath, the soft thud of her feet, quiet gym ambience. No spoken lines, no on-screen text. **Subject video**: [Watch video](https://runware.ai/docs/assets/source-fitness-instructor.D5fL-LfM.mp4) > **Prompt**: A 5-second wide interior shot of a fitness instructor in her thirties in a modern home gym, wearing a fitted black tank top and grey leggings, demonstrating a controlled goblet squat with a small kettlebell held at her chest. She is standing centred in frame on a rubber gym floor, warm mixed daylight from a window on the left. Camera locked at chest height showing her full body. She goes down into a squat, holds briefly at the bottom, and returns to standing with controlled form. Audio: her controlled exhale on each rep, the quiet ambient tone of the gym, the soft thud of her feet planting. No music, no on-screen text, no subtitles. **Product image**: ![A pair of premium matte-black over-ear wireless headphones with brushed-aluminum headband debossed READ AUDIO, sitting centred on a soft matte-white surface with soft directional daylight from the upper left](https://runware.ai/docs/assets/source-product-headphones.Wxco1sbl_ZfXu87.jpg) > **Prompt**: A photoreal editorial product hero shot of a pair of premium matte-black over-ear wireless headphones sitting centred on a soft matte-white surface. The headphones have soft black leather ear cups and a slim brushed-aluminum headband with a subtle brand debossment reading "READ AUDIO". Soft directional daylight from the upper left creates a gentle highlight on the aluminum band. Wide 16:9 framing with the headphones centred, no other objects, no additional text. **Music audio**: [Listen to audio](https://runware.ai/docs/assets/source-music.Dqc-cYx4.mp3) > **Prompt**: A slow warm ambient electronic instrumental track with soft synth pads, a gentle rhythmic pulse at 80 BPM, and a subtle bass foundation. The mood is contemplative and open. 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) > [!NOTE] > `frameImages` cannot be combined with any of the reference inputs. The composition pattern above only works with reference-type inputs together. If you need to pin a specific opening frame *and* carry a subject from a reference video, generate the two shots separately and edit them in post. ### [Input constraints](https://runware.ai/docs/models/alibaba-wan3-0/guides/video-and-audio-references#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](https://runware.ai/docs/models/alibaba-wan3-0/guides/video-and-audio-references#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.