Create video

Create Wan 3.0 text-to-video, image-to-video, or multimodal reference tasks using common platform fields.

Use top-level common fields and metadata for the platform format; do not put native input/parameters directly in this request. The platform creates tasks asynchronously. Retrieve the result after submission.

POST/v1/videos

Authorization

bearerAuth

AuthorizationBearer <token>

Use the platform API Key: Authorization: Bearer your-api-key.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Provide a prompt or nonempty metadata.media. Use JSON, not multipart/input_reference/image/images.

model*"wan3.0-video"

Model name, fixed to wan3.0-video.

Default"wan3.0-video"

Value in

"wan3.0-video"

prompt?Prompt

Describe the video, up to 20000 characters. Provide a prompt or a nonempty media array. References are numbered separately by type; use 图1, 视频1, and 音频1 in the prompt.

Lengthlength <= 20000

size?string

Resolution shortcut. Priority: nonempty size → nonempty metadata.resolution → nonempty metadata.size → 1080P. Blank strings count as omitted. Use 480P/720P/1080P, not pixel dimensions.

duration?integer

Output-duration shortcut using a JSON integer. Priority: explicit duration → nonempty seconds → metadata.duration → 5. Invalid higher-priority values do not fall back.

Range-1 <= value <= 30

seconds?string

Duration shortcut using an integer string such as "5" or "-1". Blank strings count as omitted. Lower priority than explicit duration, higher than metadata.duration. Prefer one duration field.

Match^(?:-1|[2-9]|[12][0-9]|30)$

seed?integer

Top-level seed takes priority over metadata.seed; explicit 0 is preserved.

Range-1 <= value <= 2147483647

metadata?

Wan extension parameters. Do not use input/parameters or fields from other models; only the listed business fields are accepted.

Response Body

`application/json`

curl -X POST "https://api.agtcloud.cn/v1/videos" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan3.0-video",
    "prompt": "At the seaside at dawn, the camera slowly pushes forward as a seagull glides over the water",
    "size": "720P",
    "duration": 5
  }'

{
  "id": "task_example",
  "task_id": "task_example",
  "object": "video",
  "model": "wan3.0-video",
  "status": "queued",
  "progress": 0,
  "created_at": 1792760030
}

Parameters and priority

Setting	Input and priority
Prompt and media	Provide `prompt` or nonempty `metadata.media`; images do not use top-level `image/images/input_reference`
Resolution	Nonempty `size` → nonempty `metadata.resolution` → nonempty `metadata.size` → `1080P`; use a tier, not pixel dimensions
Duration	Explicit `duration` → nonempty `seconds` → `metadata.duration` → `5`; `duration` is an integer, `seconds` an integer string
Seed	Explicit top-level `seed` takes priority over `metadata.seed`; `0` is valid
Other settings	Put aspect ratio, audio, prompt rewriting, and watermark in `metadata`; explicit `false` is preserved

Prefer one field per setting. Blank resolution and seconds strings count as omitted; prompt may be omitted when media is supplied. Invalid higher-priority values produce an error instead of falling back.

Scenarios and media

Request examples cover text, first frame, first and last frames, mixed references, files, webpages, editing, and extension. For media scenarios, replace example URLs with your own accessible URLs.

First/last-frame mode cannot include reference media; a last frame requires a first frame. Choose either a file or a webpage and enable prompt rewriting. See Media and combination rules for formats, quantities, dimensions, and durations; the same rules apply to the platform format.

Creation results and compatibility paths

Creation returns a video object. Store id and use the platform retrieval API for the result. The compatibility field task_id equals id. queued means accepted, not generated.

POST /v1/video/generations and POST /v1/videos/generations are also supported with the same parameters and response structure. Use the main endpoint POST /v1/videos for new integrations.

Common errors

For HTTP 400, use the returned error to check parameter types, resolution tiers, media combinations, and metadata field names. Errors may use code/message/data or a nested error object.

Alibaba Cloud Wan 3.0 video generation API referenceReference for the model native protocol; platform fields and responses follow this page.

Authorization

Request Body

Response Body

200application/json

400application/json

401application/json

Parameters and priority

Scenarios and media

Creation results and compatibility paths

Common errors

`application/json`

`application/json`

`application/json`