Wan 3.0 API: text-to-video vs image-to-video vs reference-to-video

Wan 3.0 is one model family with three ways in, and the way you start decides what you can control, what you pay for and, on this API, how it handles uncensored content. Whether to send words, a still or a pile of references comes down to one question.

Short answer. Ask what must not change in the clip:

• Nothing yet, you are still finding the scene: text-to-video. One field, prompt, is enough.
• The first frame (and optionally the last): image-to-video. The image is used exactly as frame one, so the prompt only has to describe motion.
• A character, a room, a voice or a movement style that must carry over: reference-to-video. Up to ten images, five clips and five audio tracks, plus an optional document or web page, each given a job in the prompt.

All three return 2 to 30 seconds with sound in the same file, at 480p, 720p or 1080p on base and Prime (Pro tiers render 1080p, 2K or 4K, with 2K and 4K enlarged from a 1080p render). Other video models are in the uncensored AI video API catalogue.

The three tasks side by side

Duration on all three tasks is 2 to 30 seconds, or -1 to let the model choose the length (30 s is held up front and the charge settles on the delivered length).

Send a field the task does not list, such as an image_url to text-to-video, and the create call returns a 400. Take the schema from the model page rather than copying a sibling endpoint.

What a clip costs

The per-second price is the same for text, image and reference input.

Reference-to-video adds one wrinkle: the seconds of any reference video are billed on top of the output, and the reference clips plus the output must stay within 30 seconds. Reference images, audio, documents and web pages are not billed. A quote or hold for a task with reference clips assumes the 15-second maximum; you are charged only for the seconds actually used.

The older Wan 2.6 is the fixed-length alternative: text-to-video and image-to-video return exactly 5, 10 or 15 seconds at 720p ($0.09 per second) or 1080p ($0.135). Its reference-to-video task is a different contract, taking up to three reference clips and no images, and it carries the Filtered content label rather than Unrestricted.

Text-to-video: write the shot, not the mood

Use it when the scene is still open, no approved image exists, or you want one long take with its own audio. Nothing anchors the opening frame, so put everything the viewer should see in the prompt: subject, one action, one camera move, then light and sound. One clear action beats a long list of adjectives. Look elsewhere when the opening composition must match an approved image: that is image-to-video.

{
  "model": "alibaba/wan-3.0/text-to-video",
  "input": {
    "prompt": "A ceramic bottle stands on a brushed-steel counter. One bead of condensation rolls down the glass while the camera pushes in slowly. Cool side light, no cut. Sound: a faint fridge hum and the tick of the droplet landing.",
    "duration_seconds": 10,
    "resolution": "720p",
    "aspect_ratio": "9:16",
    "generate_audio": true
  }
}

That request costs 10 x $0.09 = $0.90 on base Wan 3.0. Three habits help:

• Settle the look at 5 seconds before asking for 30. Longer clips drift more, so a bad idea is cheaper to find short.
• For long takes, split the prompt into timed beats. One community example wrote one two-second beat per action (dough, sauce, toppings, oven) plus a continuity line for a 15-second clip.
• Leave prompt expansion off once the brief is precise. It helps thin prompts and fights detailed ones; it is on by default on Wan 3.0 Pro text-to-video.

Image-to-video: the frame is the ceiling

Use it when frame one is not negotiable: a product packshot with a fixed crop, an approved character board, a keyframe from a previous clip. The image sets wardrobe, set and light, so the prompt only carries motion. Look elsewhere when the scene is still open (text-to-video) or a character must recur across several shots (reference-to-video). Leave aspect_ratio out and the clip inherits the image's shape; a conflicting value crops it.

last_image_url makes the clip end exactly on a second image. Passing the same file as both first and last frame gives a loop with no stitching, as in this product-bottle example: a quarter turn so the highlight crosses the glass, then back to the start.

Same image as image_url and last_image_url, sound off; 5 s at 1080p costs $0.90.

{
  "model": "alibaba/wan-3.0/image-to-video",
  "input": {
    "image_url": "https://cdn.spicyapi.ai/models/examples/inputs/e82b71db9e3d0e5f.png",
    "last_image_url": "https://cdn.spicyapi.ai/models/examples/inputs/e82b71db9e3d0e5f.png",
    "prompt": "The bottle rotates a quarter turn so the highlight travels across the glass, then returns to its starting angle. Locked camera, single soft key from the left, no music.",
    "duration_seconds": 5,
    "resolution": "1080p",
    "generate_audio": false,
    "seed": 20260907
  }
}

Describe the frame you supplied, then the motion; never a different room. When a prompt names a scene unlike the still, Wan 3.0 may open on the still and then cut to the new scene. last_image_url alone is rejected; it needs image_url.

Reference-to-video: give every reference a job

Use it when something has to recur: the same character in several shots, a specific room, a voice, a movement or camera style. Wan 3.0 reads references in the order you supply them, and the prompt says which is which; otherwise the model averages them into a subject that matches none. Look elsewhere when one approved still already says everything: extra references compete and are not automatically more control. The example below keeps a character from the first image and a room from the second.

Decorative illustration, not a model output or a diagram of the example below.

{
  "model": "alibaba/wan-3.0/reference-to-video",
  "input": {
    "reference_image_urls": [
      "https://cdn.spicyapi.ai/models/examples/inputs/a4d8d93ce949c527.png",
      "https://cdn.spicyapi.ai/models/examples/inputs/27753da99f960815.png"
    ],
    "prompt": "The first image is the character: keep her face, hair and the black slip dress exactly. The second image is the room. She crosses from the doorway to the window and leans against the frame, looking out. Slow lateral track, one practical lamp, night ambience.",
    "duration_seconds": 8,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "seed": 771120
  }
}

Two reference images, no reference video: the 8 s clip costs 8 x $0.09 = $0.72.

What you can feed it:

• Images (up to 10) for identity, wardrobe and set plates. A real person's photo is often refused by the face check ("The input content is suspected to include real human faces"). Use illustrated, 3D-rendered or generated characters. Refused tasks are not charged.
• Video (up to 5 clips, 1 to 15 s each, 15 s in total) for movement and camera style rather than for a face. Check clip lengths before submitting; limits are enforced during generation, not at acceptance.
• Audio (up to 5 clips, 15 s in total) for a voice or room tone.
• One document or one public web page (not both) that the model reads for characters, wardrobe, setting and action: a PDF, DOCX, TXT or Markdown file up to 100 MB and 50 pages, or a page that opens without a login. Attaching either switches on thinking (not available on the Pro tiers) and prompt expansion unless you set them. A creator tutorial shows the idea; a failed page read is not charged.

If frame one must be exact, use image-to-video. Reference-to-video can be told to start from an image (see Alibaba's Wan 3.0 prompt guide), but only image-to-video guarantees it.

What changes for uncensored work

Uncensored is not a single switch on Wan; the task you pick changes the outcome. Based on our September 2026 tests (full grid in the Wan uncensored test):

• Base Wan 3.0 delivered every intensity level in the test, from Mild to Maximum, across text, image and reference input, but it also goes further than you ask: a Maximum-level prompt often came back as a different scene from the one requested, sometimes with a second person added.
• Wan 3.0 Prime image-to-video toned a Very strong scene down, while Prime text and reference delivered it. If your job starts from a still, try base Wan 3.0 first.
• Wan 3.0 Spicy and Prime Spicy exist only as image-to-video (from $0.057 per second at 480p). They push scenes further than asked and often change the wardrobe. If the outfit must stay unchanged, use base Wan 3.0.
• Wan 2.6 reference-to-video refused our reference footage.

Behaviour differs by endpoint, so run your own prompt on the one you pick. For continuing a story beyond 30 seconds, see chaining clips.

Try it in the Playground first

Each task has its own page with a Playground tab (stay in Form view; sign in with a funded account to run). Run a short, cheap clip there before you write any code.

1. Open the page for your task: text to video, image to video or reference to video.
2. Fill the inputs the task needs. Text to video: Prompt. Image to video: Input image, plus Closing frame if the clip must end on a second image; Prompt is optional. Reference to video: Reference images, Reference videos and Reference audio (at least one of the reference inputs); in the prompt, say what each one controls.
3. Set Resolution to 480p and Duration to 5. Both are marked as affecting price, and the estimate on the page updates when you change them.
4. Leave Generate audio on unless you will score the clip yourself, and leave Prompt expansion off once the prompt is precise. Set a Seed if you want to compare two changes.
5. Press Run model, watch the clip in Output, then raise resolution and length once the look is right.

The JSON view beside Form shows the request body, and the code tabs next to it show the same call, so a clip that works here can be copied into your code.

Then run it from code

Install the Python SDK (pip install spicyapi), set SPICY_API_KEY in your environment, and run this. It uses the text-to-video body from above; swap the model ID and input for either of the other two tasks. It shows the price and waits for your yes before creating the task:

import uuid
from spicyapi import SpicyClient, output_assets

client = SpicyClient()  # reads SPICY_API_KEY from the environment
MODEL = "alibaba/wan-3.0/text-to-video"
body = {
    "prompt": "A ceramic bottle stands on a brushed-steel counter. One bead of condensation "
              "rolls down the glass while the camera pushes in slowly. Cool side light, no cut. "
              "Sound: a faint fridge hum and the tick of the droplet landing.",
    "duration_seconds": 10,
    "resolution": "720p",
    "aspect_ratio": "9:16",
    "generate_audio": True,
}

quote = client.quote_task(model=MODEL, input_data=body)
print("Estimated", quote["estimatedCost"], "maximum", quote["maxCharge"])
if input("Create the task? [y/N] ").strip().lower() != "y":
    raise SystemExit

task = client.create_task(
    model=MODEL,
    input_data=body,
    idempotency_key=str(uuid.uuid4()),
    quote_id=quote["quoteId"],
    expected_cost=quote["estimatedCost"],
)
print("Task", task["taskId"], flush=True)  # save it: after a timeout, look this task up instead of creating another
final = client.wait_for_terminal(task["taskId"])
if final["state"] != "succeeded":
    raise SystemExit(f"{task['taskId']} ended as {final['state']}: {final.get('errorCode')}")
assets = output_assets(final)
if not assets or any(
    not asset.get("url") or asset.get("pending") or asset.get("unavailable")
    for asset in assets
):
    raise RuntimeError(f"{task['taskId']} has no complete downloadable output; look up this task before retrying")
print(assets[0]["url"])  # copy the clip to your own storage now

For image, clip or audio inputs, use a public HTTPS link or an uploaded file (media guide). Everything beyond this call is in the tasks guide and the Python SDK reference; a service can use webhooks. Clips are kept for about 14 days, so copy the ones you want (retention and delivery).

Or let an Agent run it

When an assistant should run the clips, all three official tools show the price and ask you before a paid call.

• CLI. Put the same input object in input.json, then:

``bash spicyapi tasks create --model alibaba/wan-3.0/text-to-video --input-file input.json --wait ``

For a local still, spicyapi files upload still.png returns the spicy:// address for image_url. See the CLI docs; npx @spicyapi/cli works without installing.

• MCP server. Add the MCP server to your assistant, then ask: "Make a 10-second 9:16 clip at 720p with Wan 3.0 text-to-video from this prompt." It calls spicyapi_task_create, which stops for your price confirmation, then spicyapi_task_wait. For a file on your computer it uses spicyapi_upload_file.
• Skill. npx skills add spicyapi-ai/spicy-skill installs the Agent Skill, which has a coding assistant read the live model schema instead of guessing fields.

When the result is wrong, change one thing

When comparing two attempts, change one field and hold seed, prompt, duration and resolution. Timeouts, balance and other general errors are in the error reference.

Which tier to start with

Start on base Wan 3.0 at 480p, then raise the resolution once the look is right. Prime is faster for 36 percent more per second at 480p, or 40 percent more at 720p and 1080p; for 1080p to 4K use Pro. For fixed 5, 10 or 15 seconds, use Wan 2.6 text or image input.

FAQ

Is image-to-video better than reference-to-video for keeping a face?

If the face is in the opening frame, image-to-video: it uses the image exactly as frame one. Reference-to-video is for a face that must carry across shots, and its references steer rather than pin.

Is image-to-video better than text-to-video?

Neither is better in general. Image-to-video wins when frame one must be a specific approved visual; text-to-video wins when you are still exploring a scene from words, and it needs no source file.

Does the task type change the price?

No. The per-second price depends only on the tier and resolution; reference-to-video adds the billed seconds of any reference clip.

In short: words to explore a scene, a still to pin frame one, references for whatever must recur across shots.