Dark amber and cyan Wan 2.5 API cover: Alibaba's Wan 2.5 model family flowing through hosted routes into one unified key

If you searched for “wan 2.5 api” because a demo clip from last September finally made it to your backlog, here is the part the demo doesn’t tell you: Wan 2.5 is now a legacy option. It was released as a preview model in late September 2025, and by August 2026 Alibaba’s own newer Wan 2.6 and Wan 2.7 models have superseded it. It is still cheap, still works, and existing integrations still pin to it — but “the Wan 2.5 API” is not one official endpoint. It is a family of open models served by many platforms, each with its own route names, billing units, and request shapes.

This guide is current as of August 19, 2026. It gives you the model IDs you will actually type, a per-second price comparison across four routes in one unit, the free-quota facts nobody on the SERP mentions, a complete submit–poll–retrieve example with real response JSON, and an honest answer to “should I even use 2.5 in 2026?”. We run Modellix, an API aggregator that carries the Wan 2.5 family next to 210+ image and video models behind one key, so we disclose the commercial interest up front — the prices below come from live pages, not from a brochure.

What the Wan 2.5 API actually is

The Wan 2.5 API is an asynchronous REST interface for generating video and images with Alibaba’s open Wan 2.5 model family, released as a preview in September 2025. It covers text-to-video, image-to-video, text-to-image, and image-to-image generation with native audio synthesis, and it is served by Alibaba Cloud Model Studio and independent platforms, each with its own endpoint, model IDs, and billing.

Three facts shape every integration decision:

  1. It was a preview model by design. The Wan team shipped Wan 2.5 as a preview release to collect feedback, per the community notes from the release livestream. By 2026 the family has moved on: Wan 2.6 and then Wan 2.7 shipped with longer durations and native multi-shot support. Alibaba’s Model Studio still serves 2.5, and providers still host it, but the model pages now describe it as the older generation — ours included, which is why we say so here.
  2. The weights are open, the API is not. The model weights are distributed through Alibaba’s ModelScope platform. “The Wan 2.5 API” is never one endpoint: Alibaba Cloud serves it through Model Studio, and independent providers (fal.ai, Replicate, WaveSpeed, EvoLink, Modellix, and others) host their own routes with their own pricing.
  3. Every route is asynchronous. Video generation takes 30 seconds to a few minutes, so every provider uses the same pattern: submit a task, poll for status, retrieve the result. The differences are in the details — required fields, polling semantics, and what unit you are billed in.

Because of that, “wan 2.5 api” is really a family of questions: which model variant, which provider, which price, which request schema. The rest of this guide answers them in that order. If you are starting a new project today, also read our Wan 2.7 API guide before you commit to a model — the honest version-picking conversation happens there.

Wan 2.5 models and their API route names

Wan 2.5 ships as four task models. Each one appears under a different route string depending on where you call it, and most platforms keep the same wan2.5-* ID from Model Studio. This table is the mapping you need:

Model Task Alibaba Model Studio ID Modellix route Key params
wan2.5-t2v-preview Text → video wan2.5-t2v-preview alibaba/wan2.5-t2v-preview prompt, duration (5/10), size
wan2.5-i2v-preview Image → video (first frame) wan2.5-i2v-preview alibaba/wan2.5-i2v-preview img_url (required), prompt, resolution, audio_url
wan2.5-t2i-preview Text → image wan2.5-t2i-preview alibaba/wan2.5-t2i-preview prompt, size, n
wan2.5-i2i-preview Image → image wan2.5-i2i-preview alibaba/wan2.5-i2i-preview up to 3 reference images + prompt

All video models output 480p / 720p / 1080p at 30 fps in MP4 (H.264), in 5- or 10-second clips, with synchronized audio — that “one-step audio” capability is the defining feature of the 2.5 generation. Text-to-video and image-to-video accept an optional audio_url for custom audio, and the image-to-video variant can take audio as an input driver as well.

Two naming traps: some platforms rewrite the route string (fal.ai exposes fal-ai/wan-25-preview/image-to-video, Replicate uses wan-video/wan-2.5-t2v), and the image-to-image variant is easy to miss because most providers advertise only the video models. If you are coming from the 2.2 generation, our Wan 2.2 API guide covers that family’s naming, and the diagram below shows how the 2.5 family flows through hosted routes to a single key.

Wan 2.5 model family diagram: four preview models (T2V, I2V, T2I, I2I) flowing through Alibaba Model Studio and third-party routes into one unified API key *Figure: Wan 2.5's four task models map to per-platform route strings; an aggregator collapses them behind one key. Prices and route names verified August 19, 2026.*

What Wan 2.5 API calls cost (one unit, live prices)

Before the numbers: the single biggest source of confusion in this market is the billing unit. Alibaba and Modellix bill per second of video; WaveSpeed bills per run (one fixed price per completed video, whatever its duration); EvoLink bills per second but prices in its own credit currency. Convert everything to USD/second before comparing — and remember that a 10-second 1080p clip is not the same product at two different providers if one of them caps audio or resolution.

Route (as of 2026-08-19) Billing unit 480p 720p 1080p Free tier
Alibaba Model Studio (International) USD / second $0.05 $0.10 $0.15 50 s new-model quota
Modellix alibaba/wan2.5-t2v-preview USD / second $0.025–$0.0917 (range across resolutions) $10–30 credit, no card
Modellix alibaba/wan2.5-i2v-preview USD / second $0.0305–$0.0917 (range across resolutions) $10–30 credit, no card
EvoLink credits / second $0.038–$0.126 —
WaveSpeed USD / run ≈ $0.5 per run —

Notes that change the math:

  • Alibaba’s official list price is the reference point: Model Studio pricing shows wan2.5-t2v-preview at $0.05/sec (480p), $0.10/sec (720p), $0.15/sec (1080p) in the International scope, with the image models at $0.03/image. The same page lists a free quota of 50 seconds of video and 50 images, valid 90 days from Model Studio activation or model release — this is the “wan 2.5 api free” answer that the rest of the SERP omits.
  • Aggregator prices are real but resolution-dependent. The Modellix figures are the live ranges on our wan2.5-t2v-preview model page; the spread is the resolution ladder. For a 5-second 480p clip you are looking at roughly $0.25 at Alibaba’s list price — and about half that through aggregators that negotiate volume rates.
  • Per-run billing hides per-second cost. WaveSpeed’s ~$0.5/run for a 10-second clip is $0.05/sec equivalent — competitive at 480p, less so if the run is capped at 5 seconds. Read the fine print on duration.
  • Prices drift. Every number above was read live on August 19, 2026. Check the Alibaba Model Studio pricing page linked above, or a provider’s model page, before you commit a budget. For the broader Alibaba model family picture, our Alibaba API pricing deep-dive covers the other generations.

The price table is only the first layer. What actually lands on your invoice is the billing unit and the request shape — which is where authentication and the async contract come in.

Authentication and request basics

Every provider authenticates with a static API key; the header name is the main difference:

Provider Auth header Async opt-in
Alibaba Cloud Model Studio Authorization: Bearer $DASHSCOPE_API_KEY X-DashScope-Async: enable
Modellix Authorization: Bearer <token> implicit (jobs always async)
fal.ai Authorization: Key <key> (or FAL_KEY env) fal.queue.submit
Pollo / others x-api-key: <key> webhookUrl param

The async lifecycle is the same everywhere: create task → poll status → retrieve result. Alibaba’s text-to-video API reference documents the official flow: POST to the video-synthesis endpoint with X-DashScope-Async: enable, get a task_id (valid 24 hours), and poll — never create duplicate tasks. fal.ai and Replicate wrap the same contract in their clients.

Now the route decision. You can open accounts at three or four providers, generate keys per provider, and track five billing dashboards — or you can use one key that routes to all of them. That is the entire value proposition of an aggregator like Modellix: a single Bearer token, one billing ledger, and per-call cost logs that show input, output, and spend for each request. It is not the cheapest option on every single model, and it is not a magic router — it is a convenience layer with transparent per-call pricing, which is a trade you might not want for a two-call prototype. For more on the trade, our one-key-many-models explainer walks through when the single-key route pays for itself.

Calling Wan 2.5 end to end: submit, poll, retrieve

Here is a complete working flow against the Modellix API — the same shape works for Alibaba Model Studio with the headers swapped. The example generates a 5-second 480p clip from a first-frame image with wan2.5-i2v-preview.

Step 1 — submit the task:

1
2
3
4
5
6
7
8
9
10
curl --request POST \
  --url https://api.modellix.ai/api/v1/alibaba/wan2.5-i2v-preview \
  --header 'Authorization: Bearer $MODELLIX_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "prompt": "A slow aerial push-in over a misty pine ridge at dawn, camera drifting forward, warm amber light breaking through",
    "img_url": "https://your-bucket.example.com/first-frame.jpg",
    "duration": 5,
    "resolution": "480p"
  }'

The response returns a task reference immediately — generation itself runs in the background:

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "code": 0,
  "message": "success",
  "data": {
    "status": "pending",
    "task_id": "task-abc123",
    "model_id": "alibaba/wan2.5-i2v-preview",
    "get_result": {
      "method": "GET",
      "url": "https://api.modellix.ai/api/v1/tasks/task-abc123"
    }
  }
}

Step 2 — poll until terminal state:

1
2
3
curl --request GET \
  --url https://api.modellix.ai/api/v1/tasks/task-abc123 \
  --header 'Authorization: Bearer $MODELLIX_API_KEY'

Poll every 5–10 seconds (back off to 15–30 s for 1080p jobs, which take longer). Terminal states are completed (the payload carries the video URL) and failed. If you would rather not poll, add an X-Webhook-URL header to the submit call; Modellix then POSTs the same result payload to your endpoint when the task reaches a terminal state. Webhook receivers must return HTTP 2xx to acknowledge, and you should deduplicate on the delivery ID header — retries happen automatically on 429/5xx and network timeouts, but not on other 4xx errors.

Step 3 — handle errors by category:

Status Meaning What to do
400 Missing/invalid parameters Fix the request; never retry blindly
401 Bad or missing API key Rotate/provide a valid key
402 Insufficient balance Top up — this is the “free tier exhausted” signal
404 Unknown task/model Check the task ID or route name
429 Rate limit / concurrency exceeded Exponential backoff
500 / 503 Provider-side failure Retry up to 3 times with backoff

Full request/response schemas for the Wan routes live in the Modellix API reference. The lifecycle diagram below is the same contract every provider implements, with different labels.

Async task lifecycle diagram: POST submit returns task_id, then polling the get_result URL until status completed, then retrieving the video URL, with a failed branch for error handling *Figure: the submit → poll → retrieve lifecycle shared by every Wan 2.5 route. Verified against Modellix and Alibaba Model Studio docs, August 19, 2026.*

Errors, rate limits, and the mistakes that cost budget

Four mistakes show up repeatedly in integration threads:

  1. Comparing prices across billing units. A “$0.5 per run” price and a “$0.15 per second” price are not comparable until you know the duration and resolution each covers. Always normalize to USD/second before deciding.
  2. Assuming the free quota renews. Alibaba’s 50-second/50-image quota is a one-time grant valid 90 days — it does not reset monthly. The 402 you hit mid-production is that quota expiring, not a billing bug.
  3. Coding against 2.5’s parameter quirks as if they were stable. wan2.5-t2v-preview accepts a size parameter; the i2v variant uses resolution. Those enums differ across versions — if you later migrate to Wan 2.7, parameter names like ratio and duration (2–15 s) change. Pin your model ID explicitly instead of using “latest” aliases.
  4. Polling too hot. Video tasks run 30 s–3 min; polling every second earns you 429s and burns request budget. Back off, or use webhooks.

FAQ

Is the Wan 2.5 API free? Partially. Alibaba Cloud Model Studio grants a one-time free quota of 50 seconds of video and 50 images per qualifying model, valid 90 days from activation. Modellix offers $10–30 of free credit on signup without a credit card. After that, it is pay-as-you-go at per-second or per-image rates.

How do I get a Wan 2.5 API key? Sign up at any provider hosting the model: Alibaba Cloud Model Studio, fal.ai, Replicate, WaveSpeed, or an aggregator like Modellix. The key is a static token you send in the authorization header. With an aggregator, one key covers Wan 2.5 and 210+ other models.

What’s the difference between Wan 2.5 T2V and I2V? T2V (wan2.5-t2v-preview) generates video from a text prompt. I2V (wan2.5-i2v-preview) animates a first-frame image, which gives you much tighter control over composition and character — at the cost of requiring a valid image URL or upload.

Wan 2.5 vs SkyReels: which should I use? SkyReels (ByteDance) and Wan 2.5 are both open Chinese video models popular on API platforms. SkyReels is stronger for consistent characters and human motion across shots; Wan 2.5’s edge is one-step synchronized audio and a lower entry price tier. For API work, the deciding factor is usually which model your platform routes and at what per-second price — compare live pages for SkyReels and Wan 2.5 rather than going on benchmarks alone.

Is Wan 2.5 open source? The weights are openly distributed via Alibaba’s ModelScope platform for preview use, but the APIs that serve it are commercial — “open weights” does not mean free inference. If you need to self-host, the ModelScope repos are the starting point; if you just need an API, the provider routes above are faster.

Is Wan 2.5 still worth using in 2026? For new projects, mostly no — Wan 2.6/2.7 are meaningfully better and only modestly more expensive. For existing integrations pinned to 2.5, it remains a cheap, stable option, and 480p output is still one of the cheapest open video tiers you can call over an API. Treat it as the budget/legacy choice, not the state of the art.

How long does Wan 2.5 generation take? Roughly 1–3 minutes for a 10-second clip, less for 480p and 5-second jobs. The API returns a task ID immediately and the result asynchronously — plan your UX around polling or webhooks, not synchronous waits.

Pricing and model availability verified August 19, 2026, against Alibaba Cloud Model Studio, fal.ai, Replicate, WaveSpeed, EvoLink, and Modellix live pages. Video-generation pricing changes frequently; always confirm on the provider’s current pricing page before committing budget. Modellix is an API aggregator that carries the Wan 2.5 family; we disclose that interest and have not altered any third-party figures.

Ready to skip the five-key spreadsheet? Browse the Wan models on Modellix — one key, live per-call pricing, no monthly fee.