Wan 3.0 Prime API Guide: Text, First/Last Frame and Reference Video

TL;DR

• Wan 3.0 Prime is the fast tier of Alibaba's Wan 3.0, model id wan3.0-video-prime. One model handles text-to-video, first/last-frame video, and reference-to-video, and references can be images, audio, or even a document or a web page. Clips run 2–30 seconds with sound on by default. Try it on the model page.
• Billed per second: $0.0875 at 480P, $0.18 at 720P, $0.36 at 1080P. A 5-second 480P clip is $0.4375.
• Two gotchas: resolution must be uppercase (480P / 720P / 1080P) and defaults to 1080P, and Prime doesn't accept reference videos.

What it produces

Text-to-video at 480P for 5 seconds, with sound. Turn the audio on to hear the rain, traffic, and grill:

VIDEO

Rain streaking down a narrow neon-lit alley at night; a slow dolly-forward past
steaming street-food stalls, magenta and cyan reflections rippling in the wet
pavement, a tabby cat darting between crates mid-shot. Ambient sound: steady
rain, distant traffic hiss, the sizzle of a grill and a low synth drone.

Generate with this prompt → (5 seconds, 480P, 16:9, sound on)

wan3.0-video-prime, 480P, 5 seconds, with sound, $0.4375.

Reference-to-video: one image of a ceramic fox figurine, animated while keeping its look.

VIDEO

Bring the referenced ceramic fox figurine to life: it slowly turns its head
toward camera, blinks, and tilts with a curious expression; subtle idle
breathing, a light breeze stirring the tiny scarf, soft studio key light on a
clean seamless backdrop, smooth loopable motion.

Generate with this prompt → (upload your reference image, 5 seconds, 480P, 9:16)

wan3.0-video-prime, reference image, 480P, 5 seconds, 9:16, $0.4375.

curl: your first clip

5 seconds at 480P, $0.4375:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan3.0-video-prime",
    "input": {
      "prompt": "An orange cat yawns on a sunlit windowsill, tail swaying, slow push-in, warm tones",
      "resolution": "480P",
      "duration": 5,
      "aspect_ratio": "16:9",
      "audio": false
    }
  }'

The response returns data.taskId. Poll GET /v1/tasks/{taskId} until status is success, then download output[0].url.

Python: submit, poll, download

# pip install requests; export HIAPI_KEY=your-key
import os, time, uuid, requests

API = "https://api.hiapi.ai/v1/tasks"
H = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

def generate(timeout_s=900, **inp):
    # Reuse the same Idempotency-Key if you retry this submission, so it is billed once
    r = requests.post(API, json={"model": "wan3.0-video-prime", "input": inp},
                      headers={**H, "Idempotency-Key": str(uuid.uuid4())}, timeout=30)
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        d = requests.get(f"{API}/{task_id}", headers=H, timeout=30).json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] == "fail":
            raise RuntimeError(d)
        time.sleep(10)
    raise TimeoutError(task_id)

# Reference-to-video: animate a product from a photo, 480P, 5 s ($0.4375)
url = generate(
    prompt="The perfume bottle from the reference turns slowly on black marble, rim light sweeping across the glass, slow push-in",
    reference_image_urls=["https://your-cdn.example.com/perfume.jpg"],
    resolution="480P", duration=5, aspect_ratio="9:16", audio=False,
)
with open("clip.mp4", "wb") as f:
    f.write(requests.get(url).content)

Three ways to use it

Document and web references are what set Wan 3.0 apart: you can hand the model a brand-guide PDF or a product page and have it build the shot from what's in it. The page must open without a login.

Input reference

Cost

Draft at 480P, then re-run the keeper at 720P or 1080P. If speed doesn't matter, standard Wan 3.0 (wan3.0-video) is $0.08 per second at 720P and also accepts reference videos. Full breakdown: Wan 3.0 Prime API pricing.

Before you ship

• Use a callback instead of polling: add "callback": {"url": "https://your-app.example.com/hiapi/callback"} next to input and deduplicate by taskId.
• Save the output right away: output[0].url is temporary.
• Send an Idempotency-Key header: retries with the same key create the task only once.
• Failed tasks are refunded.

FAQ

Why does 720p fail?

Resolution must be uppercase. Lowercase returns HTTP 400: resolution: value must be one of '480P', '720P', '1080P'.

Can I send a reference video?

Not on Prime: reference_video_urls returns HTTP 400. Use standard Wan 3.0 (wan3.0-video) for reference videos.

Can I turn sound off?

Yes, audio: false. It's on by default and doesn't change the price.

How is Prime different from standard Wan 3.0?

Same inputs and output spec, but Prime generates faster and lists a 480P price. It costs 2.25× as much per second at 720P and 1080P, and doesn't take reference videos.

More prompts: Wan 3.0 Prime prompt recipes. Comparison with the previous generation: Wan 3.0 vs Wan 2.7. Or generate the rainy alley clip on the model page.