How to Get Started with Wan 2.5 Preview

Wan 2.5 Preview is a video generation tool by Alibaba that turns text descriptions or images into short cinematic clips with synchronized audio. It supports two modes: text-to-video (T2V) and image-to-video (I2V). Other high-performance models like Kling V3 offer similar cinematic capabilities. Key features include one-pass audio-visual creation, precise lip-syncing, and outputs up to 1080p at 24fps for 5- or 10-second videos. Integration is made easy through APIMart, a platform offering a unified API for seamless access. Pricing starts at $0.0336/second for 480p. Here's what you need to know to get started:

• Modes: T2V for creating videos from text prompts, I2V for adding motion to images.
• Quality: Outputs in 480p, 720p, or 1080p with 48kHz stereo audio.
• Pricing: Pay-as-you-go, billed per second of video generated.
• Setup: Works with Python or Node.js using a REST API. Requires an API key from APIMart.
• Workflow: Submit a request, get a task ID, and poll for the result.

Start with a 5-second 480p clip to test your setup. Once comfortable, scale up to 1080p for final renders. Use detailed prompts for better results, and incorporate audio instructions for synchronized sound.

This guide covers everything from setting up your environment to crafting prompts and managing costs effectively.

Setting Up Your Environment

Developer Prerequisites

Before diving into the code, it's crucial to be familiar with some basics. You should have a good grasp of REST APIs and JSON formatting, as all interactions with Wan 2.5 rely on these standards. Whether you prefer Python 3.x or Node.js (v14+), either will work for this setup.

Another key concept to understand is asynchronous workflows. Wan 2.5 doesn't deliver a finished video immediately. Instead, it provides a task_id that you’ll need to monitor. You'll have to create a polling loop to check the task status until it updates to "completed." Once you're ready, head over to APIMart to create an account and get your API key.

Creating an APIMart Account and API Key

Start by visiting apimart.ai to set up a free account. After signing in, go to the API Key Management section in your Console Dashboard to generate your API key. Make sure to copy and securely store your key right away - it’s displayed only once.

APIMart uses a pay-as-you-go model, so you’ll need to fund your account before making requests. If you encounter a 402 error, it means your account balance is too low. A 401 error, on the other hand, indicates an issue with your API key. Double-check your credentials and ensure your account has sufficient funds.

Configuring Your Development Environment

With your API key ready, setting up your environment is simple. APIMart is compatible with the OpenAI SDK. To get started:

• For Python: Run pip install openai
• For Node.js: Run npm install openai

The only adjustment from a standard OpenAI setup is the base URL. Set it to:

https://api.apimart.ai/v1

Authenticate your requests by including your API key as a Bearer token in the header, like this:

Authorization: Bearer YOUR_API_KEY

For added security, avoid hardcoding your API key directly into your scripts. Instead, store it in an environment variable. Using a .env file during local development is a good practice to keep your credentials safe and out of version control. Once your environment is configured, you can move on to making your first API requests.

Making Your First API Requests

Text-to-Video Request Example

Once you're set up, you can dive into your first API request! As mentioned earlier, these requests are asynchronous, meaning you'll need to wait for the task to complete before getting your results.

Here’s a simple Python example to start generating a text-to-video output:

import openai
import os

client = openai.OpenAI(
    api_key=os.environ["APIMART_API_KEY"],
    base_url="https://api.apimart.ai/v1"
)

response = client.post("/wan2.5-t2v-preview", json={
    "model": "wan2.5-t2v-preview",
    "input": {
        "prompt": "A golden retriever runs along a sunlit beach, waves crashing in slow motion",
        "negative_prompt": "low quality, blurry, distorted",
        "duration": 5,
        "size": "1280*720",
        "prompt_extend": True
    }
})

task_id = response.json()["task_id"]
print(f"Task started: {task_id}")

The only required field here is prompt, which describes the scene you want to create. Other parameters, like negative_prompt and size, help refine the output. If your prompt is short, setting prompt_extend to true allows the model to expand it into a more detailed, cinematic description. Remember to use exact dimensions, like 1280*720, instead of aspect ratios.

After submitting your request, you’ll receive a task_id. Use this ID to poll the status endpoint until your task is marked as SUCCEEDED:

import time

while True:
    result = client.get(f"/tasks/{task_id}")
    status = result.json()["task_status"]
    if status == "SUCCEEDED":
        video_url = result.json()["video_url"]
        print(f"Video ready: {video_url}")
        break
    elif status == "FAILED":
        print("Generation failed.")
        break
    time.sleep(15)

Video generation usually takes 1–5 minutes. Once your video is ready, download it within 24 hours, as the URL will expire after that.

Next, let’s look at how to generate videos from images using a similar approach. You can also explore other models like Grok Imagine Video for different cinematic styles.

Image-to-Video Request Example

The image-to-video (I2V) process follows the same asynchronous workflow but includes two key differences: you need to specify the wan2.5-i2v-preview model and provide an image_url pointing to the source image.

Here’s an example:

response = client.post("/wan2.5-i2v-preview", json={
    "model": "wan2.5-i2v-preview",
    "input": {
        "image_url": "https://your-storage.com/character-portrait.jpg",
        "prompt": "The character slowly turns their head and smiles at the camera",
        "duration": 5,
        "resolution": "720p",
        "negative_prompt": "blurry, artifacts"
    }
})

For I2V, the prompt should describe motion or changes relative to the starting image - such as character movements or camera actions. The aspect ratio will match your source image, so make sure it’s cropped to the desired ratio (e.g., 16:9, 9:16, 1:1) before submitting. Source images should be between 360 and 2,000 pixels on either side and no larger than 10 MB.

Just like with text-to-video, capture the task_id from the response and use the same polling logic to track the task status until it’s completed.

Now, let’s break down the structure of the API responses to understand what each field means.

Understanding API Responses

When you make a successful POST request, the API returns a JSON object containing a task_id that you can use to check the task’s progress. Once the task is finished, you’ll receive the following fields:

A 200 HTTP status code and a valid task_id mean your request was accepted. If the task ultimately fails, check the error.message field for details, such as unsupported resolution formats or an overly long prompt.

Wan 2.5 (the Veo 3 Killer) is NOW in n8n (full tutorial & template)

Optimizing Prompts and Configurations

Once your environment is set up and you've made initial API requests (or explored the newer WAN 2.6 API), fine-tuning your prompts can greatly improve the quality of your video outputs.

Writing Good Text and Image Prompts

The results you get depend heavily on how well you craft your prompts. For Wan 2.5, prompts between 80 and 120 words work best - long enough to provide clear guidance but not so long that they confuse the model.

Here’s a helpful structure to follow: start with the subject or scene, then add camera movements, motion details, and visual style. For example, instead of saying "a woman walking in a city," you could write: "A woman in a red coat walks briskly through a rain-soaked Manhattan street at dusk. Dolly in slowly. Puddles reflect neon signs. Teal-and-orange color grade, anamorphic bokeh, volumetric dusk lighting." This level of detail gives the model clear instructions for mood, composition, and motion.

To control the camera, use standard cinematography terms like Pan left/right, Tilt up/down, Dolly in/out, Orbital arc, or Crane up/down. Add depth by describing parallax effects - “foreground grass sways while mountains remain still in the background.” You can also adjust pacing with terms like "slow-motion" or "whip-pan (a quick camera pan).”

For image-to-video tasks, focus on describing motion or expression changes since the model uses the provided image as a base reference.

Once your visual prompt is locked in, you can take it a step further by incorporating synchronized audio and dialogue.

Adding Audio and Dialogue

One of Wan 2.5's standout features is its ability to generate both video and audio simultaneously, creating a fully synchronized experience with voice, ambient sounds, and effects.

"What truly sets Wan 2.5 apart is its ability to generate not just silent videos, but complete audio-visual experiences in a single pass." - Scenario Knowledge Base ^[9]

For lip-synced dialogue, include character speech in quotation marks, like this: "A scientist looks into the camera and says, 'The results are extraordinary.'" For environmental sounds, be specific: "rain taps against a window, distant traffic hums." The model integrates these details into the final output automatically.

If you want to use your own audio, you can provide a custom audio_url in .wav or .mp3 format (max size: 15 MB). However, the audio file should match the video duration; if it's shorter, the remaining frames will be silent. Be cautious when combining audio_url with multiple image or video URLs in a single request, as this can lead to conflicts ^[4].

The model automatically matches the audio language to your prompt, so if your prompt is in English, the audio will also be in English - no extra steps required ^[10].

This level of synchronization ensures that the audio and visuals work together seamlessly for a polished final result.

Choosing Resolution and Duration

When working with API requests, selecting the right resolution and duration is key to balancing quality and cost.

Wan 2.5 Preview offers two fixed durations - 5 seconds or 10 seconds - and resolutions of 480p, 720p, and 1080p at 24 fps. Start with a 5-second draft at 480p to test your concept, then scale up to 1080p for your final render.

Here’s a quick reference for common use cases:

All resolutions include 48kHz stereo audio, so even a low-resolution draft will give you a good sense of how the audio will sound before committing to a higher-quality render.

Integrating Wan 2.5 into Multi-Modal Workflows

Once you've dabbled with API experiments, it's time to integrate Wan 2.5 into your production pipeline. With APIMart, you gain access to over 500 AI models through a single API. This setup allows you to seamlessly combine language, image, and video models without needing extra configurations.

Building a Script-to-Video Pipeline

Here’s a common workflow: start with a language model to draft a script and divide it into scenes. Next, use an image generation model to create a storyboard for each scene. From there, Wan 2.5 steps in, taking the storyboard and scene descriptions to produce a video clip. It even synchronizes audio in one go, simplifying the process ^[2][5].

By keeping everything within APIMart, you streamline your workflow. You’ll only need to manage one API structure, one authentication key, and a single billing dashboard. With this setup, you can focus on fine-tuning the balance between performance and cost.

Managing Costs and Performance

To manage expenses effectively, tailor the model and resolution to the current stage of your project. For early drafts, use 480p resolution for 5-second clips, which costs 43 credits per clip. Once your draft is approved, upgrade to 720p at 85 credits for 5 seconds or 170 credits for 10 seconds. For final renders, bump it up to 1080p at 128 credits for 5 seconds or 255 credits for 10 seconds ^[1].

Need faster iterations? The wan-2.5-fast variant offers a more cost-efficient option for 1080p, reducing the cost for a 10-second clip to 174 credits instead of 255 credits ^[11]. If you're tackling image-to-video tasks at scale, the wan2.6-i2v-flash model is a budget-friendly choice, charging $0.0168 per second at 720p compared to $0.05 per second for the standard Wan 2.6 ^[7].

Workflow Example: From Concept to Final Video

Once you've optimized costs and performance, follow this step-by-step process to bring your concept to life:

• Write the script: Use a language model like GPT-5 (available via APIMart) to craft detailed scene descriptions. Include specific audio cues, such as "soft piano music fades in" or "distant city traffic hums."
• Generate storyboards and draft scenes at 480p: Feed scene descriptions into an image model to create visual guides. Then, test each scene with Wan 2.5 at 480p for 5 seconds to evaluate motion, pacing, and audio synchronization.
• Final render at 1080p: Once satisfied with the drafts, re-render the scenes at 1080p for a polished 10-second MP4 output, complete with native 48kHz stereo audio ^[8].

"The consistency of WAN 2.6 is amazing! Character images remain stable across multiple clips, which was previously hard to achieve." - Wei Zhang, Independent Animator ^[7]

For an extra boost during the final render, use the enable_prompt_expansion parameter. This feature automatically enriches your prompts with cinematic details, elevating the quality of your output without requiring additional manual adjustments ^[12][3].

Conclusion and Next Steps

Now you’re equipped with the tools to dive into creating your first Wan 2.5 video. With its built-in one-pass audio-video synchronization, support for resolutions up to 1080p, and versatile input modes like text-to-video and image-to-video, this model is ready for serious production work - not just casual trials.

Before jumping in, ensure your setup is fully prepared. Start small by testing a 480p clip to fine-tune your prompts. Once you’ve nailed the process, scale up to 1080p for your final renders. This approach allows you to experiment and refine without committing too many resources upfront.

For your first project, try focusing on a single scene. Write a detailed prompt that includes clear audio instructions, and generate a short 5-second clip. Processing times are quick - usually between 1 and 5 minutes - and the cost is manageable, starting at just $0.0336 per second for 480p clips ^[6]. It’s an affordable way to explore and get comfortable with the tool.

When you’re ready to expand, take advantage of APIMart’s library of over 500 AI models. With a single API key and billing dashboard, you can streamline your workflow and create a full script-to-video pipeline with ease, or explore alternatives like MiniMax-Hailuo 2.3 for high-quality consistency.

FAQs

How do I handle polling and timeouts for long-running video tasks?

For production workflows, it's efficient to use the callbackUrl parameter when creating a task. This way, you'll automatically receive a POST request once the task is complete.

If you prefer polling, here's how it works: submit your task to get a taskId, then wait 50 seconds before querying the status endpoint. After that, check the status every 5 seconds. To prevent overloading the system, make sure to handle 429 errors by pausing and retrying after a delay.

What’s the best way to estimate cost before generating a 5s or 10s clip?

To figure out the cost of a 5-second or 10-second video clip, simply multiply the clip's duration (in seconds) by the provider's per-second rate. Make sure to check the rate for the resolution you want - whether it's 480p, 720p, or 1080p - since higher quality usually comes with a higher price. For example, if you're calculating for a 5-second clip, multiply the per-second rate by 5. For a 10-second clip, multiply it by 10.

How can I improve lip-sync and dialogue quality with my prompts?

To get the best lip-sync and dialogue quality in Wan 2.5 Preview, use structured prompts. These should clearly specify the character's lines, along with details like emotion, tone, speed, and timbre. This level of detail helps the model deliver more accurate and natural results.

For even greater precision, you can upload a custom audio file in WAV or MP3 format. This file will act as a guide for the model to align facial expressions and mouth movements with the audio perfectly.

Make sure your input image is sharp and well-lit. A high-quality image ensures the model can interpret and replicate expressions effectively. Additionally, take advantage of the prompt extension feature, which allows you to include detailed descriptions for better interpretation by the model.