Create task

Submit a alibaba/wan3.0-video-prime generation task to /v1/tasks: an id is returned immediately and the video is produced in the background.

This model is the high-speed tier of its generation and accepts field-for-field identical parameters to the other tier; the trade-off between them is covered on the protocol-level page.

Authorization

header

AuthorizationstringRequired

Bearer <your Amux key> Your Amux API key.

Request

application/json

modelstringRequired

The Amux model ID.

promptstring

A description of what to generate. Chinese and English are supported, up to 20,000 characters; anything beyond that is truncated upstream rather than rejected. The prompt may refer to items in media as "Image 1", "Video 1".

mediaarray<object>

Input material, each item identified by its type. **Only publicly reachable https

URLs are accepted**; the oss:// addresses and image base64 payloads Alibaba Model

Studio supports are not.

A request may carry at most 24 items, a ceiling normal usage does not reach.

›mediaarray<object>

type"first_frame" | "last_frame" | "reference_image" | "reference_video" | "reference_audio" | "file" | "link"Required

What this item is used for. Three combination rules:

1. Frames and references are mutually exclusive (first_frame / last_frame

cannot appear alongside any reference_*);

2. file and link are mutually exclusive;

3. At most one first_frame and one last_frame; multiple reference images are

permitted.

Upstream limits per role:

Role	Max count	Formats	Limits
first_frame / last_frame	1 each	JPEG/JPG/PNG/BMP/WEBP	≤20MB, 240-8000px per side, aspect ratio ≤8:1
reference_image	10	Same	Same
reference_video	5 clips	MP4/MOV	≤100MB and 1-15s per clip, ≤15s total, ≥16fps
reference_audio	5 clips	WAV/MP3	≤15MB total, 1-15s per clip, ≤15s total
file	1	DOCX/DOC/XLSX/XLS/PPTX/PPT/PDF/TXT/KEY/PAGES/NUMBERS/MD	≤100MB, ≤50 pages
link	1	Public web page	Must not require a login

The counts above are validated upstream and are not re-validated here; Amux applies

only the overall 24-item ceiling.

urlstringRequired

A publicly reachable https URL. The model fetches this address; Amux does not.

resolution"480P" | "720P" | "1080P"Default "1080P"

Output resolution tier. This field is the billing dimension — the unit price is the per-second rate for the selected tier.

aspect_ratio"adaptive" | "16:9" | "4:3" | "1:1" | "3:4" | "9:16"Default "adaptive"

Aspect ratio. adaptive follows the input material.

On this endpoint the parameter is named aspect_ratio; on the Model Studio

endpoint it is ratio. The two are equivalent.

durationintegerDefault 5

Seconds of output. 2-30 without video input; with a reference video, input duration

plus output duration must not exceed 30.

-1 selects smart duration, letting the model choose the length. The reservation

then covers a 30-second upper bound, since the actual length cannot be known at

submit time; the task settles against the seconds actually produced and the

difference is released.

audiobooleanDefault true

Whether the output carries sound. Does not change the price. The output frame rate is fixed at 30fps and is not configurable.

seedinteger

Reproducibility seed. -1 or 0-2147483647. Randomly generated when omitted.

prompt_extendbooleanDefault true

Whether the model rewrites and expands the prompt before generating.

watermarkbooleanDefault false

Whether to stamp a watermark on the output video.

webhook_urlstring

POST the result to this address once the task reaches a terminal state. **https only,

and it must not point inside a private network. The address is validated at

submit time**, so an incorrect address fails immediately rather than after the task

completes and the callback cannot be delivered.

Payload shape and signature verification are documented in

Create task.

Response

200response

Task accepted and the reservation is held. Use id to retrieve the result.

400response

Invalid parameters, or an input-media combination this model rejects.

402response

Insufficient balance to cover the reserved upper bound. With duration: -1 the reservation covers 30 seconds; specifying an explicit duration reduces the amount held.

503response

No provider can currently serve this model.

Differences from the Model Studio endpoint#

There are exactly two. Everything else — routing, pricing, reservation, idempotency, rate limits, task records — is identical:

The second row needs particular attention: the same parameter carries a different name on each endpoint. Sending ratio to this endpoint is not an error but has no effect — a request for 16:9 yields the material-driven ratio instead.

This endpoint is vendor-independent: when another video upstream is added, code using it needs no changes, whereas the Model Studio endpoint applies by definition only to Model Studio models.

Input material#

Each item in media carries a type field identifying its role. Per-role counts, formats and size limits are listed on the media[].type row in the parameter panel above; that table is generated from the interface specification.

Three combination rules, returning 400 when violated:

1. Frames and references are mutually exclusive: first_frame / last_frame cannot appear alongside any reference_*;
2. file and link are mutually exclusive;
3. At most one first_frame and one last_frame; multiple reference images are permitted.

All other combinations are forwarded to the model for validation.

Input material must be a publicly reachable https URL. The oss:// addresses and image base64 payloads that Alibaba Model Studio accepts are not supported on either Amux endpoint; non-https addresses and addresses resolving to private networks return 400.

A single request may carry at most 24 items, a ceiling normal usage does not reach. Per-type counts are validated upstream.

Three parameters that need attention#

prompt is not required. The requirement is "prompt or media, at least one"; a first-frame image without a prompt is a valid request. Prompts accept Chinese and English; anything beyond 20,000 characters is truncated upstream rather than rejected.

Valid duration values are 2-30 or -1, excluding 0 and 1.

audio does not change the price. The output frame rate is fixed at 30fps and is not configurable.

Billing#

Video produces no tokens. The charge is the per-second rate for the requested resolution tier multiplied by the seconds actually produced; input material is not priced separately.

A reservation is held against an upper bound at submit time, then settled against actual usage with the difference released.

A duration of -1 (smart duration) reserves against a 30-second bound. The actual length is chosen by the model and cannot be known at submit time, so the reservation must cover the longest possible result. Note the side effect: an account holding only enough balance for 10 seconds of 1080P receives a 402 on -1, even though the call's actual cost may be within its balance. Specify an explicit duration to reduce the amount held.

Failures and timeouts are not charged and the reservation is released. Per-tier prices are on this model's page in the model catalog.

Callbacks, idempotency keys and Prefer: wait#

All three behave exactly as they do for image tasks and are documented in Create task: the callback payload shape, how to verify Amux-Signature, the retry schedule, and the scope of an idempotency key.

One point deserves particular mention: webhook_url is validated at submit time. An incorrect address fails immediately rather than after the task completes and the callback cannot be delivered. Given how long video tasks run, the latter means either waiting for nothing or resubmitting and paying again.

Errors#

The type values and retry semantics are in Errors and retries.

curl https://gateway.amux.ai/v1/tasks \
  -H "Authorization: Bearer $AMUX_API_KEY" \
  -d '{
    "model": "alibaba/wan3.0-video-prime",
    "prompt": "A ginger cat running through fresh snow, slow motion",
    "resolution": "1080P",
    "duration": 5
  }'

{
  "id": "task_01M1CG35C16CJ790D00BV1RBVM",
  "status": "queued",
  "model": "alibaba/wan3.0-video-prime",
  "created_at": "<string>",
  "output": {
    "images": [
      {}
    ],
    "videos": [
      {
        "index": 0,
        "url": "<string>"
      }
    ]
  },
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0,
    "total_tokens": 0,
    "output_video_seconds": 0
  },
  "cost": "1.271995",
  "error": {
    "message": "<string>",
    "code": "<string>"
  }
}