API protocol

Wan 3.0: parameters, scenarios and API guide

Preview guide

Paste into an AI assistant to help with integration. Documentation and examples only; no real credentials.

Preview guide

Wan 3.0: parameters, scenarios and API guide

Direct answerinput_reference means one first-frame image. Use URL arrays reference_videos and reference_audio for video and audio.

Updated · Reviewed

Purpose and workflows

Use for product shots, motion references, image animation, sound and document-based videos. Choose frame control or multimodal references explicitly.

This guide checks the site request contract; it does not claim paid generation acceptance for every scenario. Use the exact model, group and available endpoint shown in the marketplace. Replace example.com media and placeholder task IDs. Confirm a minimal request before adding references and advanced parameters. Consult marketplace pricing and actual billing for charges.

Models and endpoints

wan3.0-video

POST /v1/videos

Reference media formats

MediaFieldsEncoding and transportPreparation and limits
Images / framesinput_reference / first_frame / last_frame / reference_images[]HTTP(S) image URL or full data:image/<format>;base64,... URI; no raw Base64.PNG/JPEG/WebP/BMP; inline images at most 20 MiB decoded. Up to 10 reference images; frames cannot mix with multimodal references.
Reference / edit videoreference_videos[]Array of HTTP(S) video URLs; no raw Base64, video data URI or local path.Prefer MP4 (H.264); at most 5 clips totaling 15 seconds. Never put video in input_reference.
Reference audioreference_audio[]Array of HTTP(S) audio URLs, not voice_id; no raw Base64 or audio data URI.Prefer WAV/MP3; at most 5 clips totaling 15 seconds. The generation service must fetch the URL directly; the previous WAV download failed, so audio reference remains unverified.
Document / webpagefile / linkPublic HTTP(S) URL, not a local file path.Choose one and enable prompt_extend. Local files are not uploaded automatically.

Parameters and combinations

  • input_reference means one first-frame image. Use URL arrays reference_videos and reference_audio for video and audio.
  • Do not mix frames with reference_images/reference_videos/reference_audio/file/link. last_frame requires first_frame.
  • At most 10 images, 5 videos and 5 audio clips; video and audio references each total at most 15 seconds. Input plus output video must fit in 30 seconds.
  • Reference each media type in order using 图片1 / 视频1 / 音频1. file and link are mutually exclusive and require public access and prompt_extend.
  • seconds and size are compatibility aliases. Prefer explicit duration/resolution/ratio without duplicate fields. Audio references do not need voice_id.
  • 2026-11-15 main-site checks: two-second frame and reference_videos tasks completed and decoded. The public WAV reference_audio case failed during media download; audio reference is not accepted yet. Client reachability does not prove generation-service access.
FieldTypeUse and constraints
Authorizationheader stringRequired: Bearer <site API key>, with Content-Type: application/json. Provider credentials and regional endpoints are managed by the service.
modelstringRequired: wan3.0-video. The official prime variant is not established as available here.
promptstringMaps to input.prompt. Supply prompt or media; official limit 20,000 characters. Number image, video and audio references separately.
first_framestringFirst image URL, mapped to input.media with type=first_frame; at most one.
last_framestringLast image, mapped to type=last_frame; one at most, requires a first frame and excludes reference media.
reference_imagesstring[]Maps to reference_image; up to 10 JPEG/JPG/PNG/WEBP/BMP images, each ≤20 MB. Public URLs or image data URIs with MIME.
reference_videosstring[]Maps to reference_video; up to 5 clips, 1–15s each, total ≤15s, ≤100 MB each. Use reachable media URLs.
reference_audiostring[]Maps to reference_audio; up to 5 clips, 1–15s each, total ≤15s, ≤15 MB each. See the known download failure above.
filestringMaps to type=file; one public document URL, mutually exclusive with link; requires prompt_extend=true.
linkstringMaps to type=link; one public web page without login, excludes file and requires prompt_extend=true.
durationintegerMaps to parameters.duration; optional, default 5; 2–30s or -1 automatic. Input plus output video must total ≤30s.
resolutionstringMaps to parameters.resolution: 480P/720P/1080P. Official default 1080P; site routes may set defaults, so specify it explicitly.
ratiostringMaps to parameters.ratio: adaptive/21:9/16:9/4:3/1:1/3:4/9:16. Official default adaptive; recommended for frames and editing.
audiobooleanMaps to parameters.audio; optional, default true; false removes audio without changing the official sound-toggle price.
watermarkbooleanMaps to parameters.watermark; optional, default false; explicit false is preserved.
prompt_extendbooleanMaps to parameters.prompt_extend; optional, default true; rewriting can add latency and is required with file/link.
seedintegerMaps to parameters.seed; optional, -1 or 0–2147483647; random by default. Reproducibility is not guaranteed.
input_reference / seconds / sizesite aliasesSite aliases for first frame, duration and pixel size. Prefer the canonical fields above without duplicating a setting.
input / input.media[].type / input.media[].urlofficial objectOfficial nested input shape. Flat mappings are above. Native Wan routes accept model+input+parameters; do not assume other routes do. Prefer the site flat examples.
X-DashScope-Asyncofficial headerOfficial creation requires enable; the site adapter supplies the upstream header. Use the unified site video endpoint.

Scenarios and code examples

Text and sound

Applies to: wan3.0-video

POST /v1/videos

{
  "model": "wan3.0-video",
  "prompt": "雨后街道,镜头缓慢推进,雨滴声清晰。",
  "duration": 8,
  "resolution": "720P",
  "ratio": "16:9",
  "audio": true,
  "watermark": false
}

curl

curl --fail-with-body --silent --show-error --connect-timeout 10 --max-time 120 --request POST 'https://api.tu-zi.com/v1/videos' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "wan3.0-video",
  "prompt": "雨后街道,镜头缓慢推进,雨滴声清晰。",
  "duration": 8,
  "resolution": "720P",
  "ratio": "16:9",
  "audio": true,
  "watermark": false
}'

python

import json
import os
import requests

url = "https://api.tu-zi.com/v1/videos"
headers = json.loads("{\"Authorization\":\"Bearer YOUR_API_KEY\",\"Content-Type\":\"application/json\"}")
for name in ["API_KEY"]:
    if not os.environ.get(name, "").strip():
        raise RuntimeError("Set environment variable: " + name)
headers["Authorization"] = "Bearer " + os.environ["API_KEY"]
payload = json.loads("{\"model\":\"wan3.0-video\",\"prompt\":\"雨后街道,镜头缓慢推进,雨滴声清晰。\",\"duration\":8,\"resolution\":\"720P\",\"ratio\":\"16:9\",\"audio\":true,\"watermark\":false}")
response = requests.request("POST", url, headers=headers, json=payload, timeout=120)
response.raise_for_status()
result = response.json()
if isinstance(result, dict) and (result.get("success") is False or result.get("code") is False or result.get("error")):
    raise RuntimeError(json.dumps(result, ensure_ascii=False))
print(json.dumps(result, ensure_ascii=False, indent=2))

javascript

// Node.js 20+
const url = "https://api.tu-zi.com/v1/videos";
const headers = {
  "Authorization": "Bearer YOUR_API_KEY",
  "Content-Type": "application/json"
};
for (const name of ["API_KEY"]) {
  if (!process.env[name]?.trim()) throw new Error("Set environment variable: " + name);
}
headers.Authorization = 'Bearer ' + process.env.API_KEY;
const response = await fetch(url, { method: "POST", headers, body: JSON.stringify({
  "model": "wan3.0-video",
  "prompt": "雨后街道,镜头缓慢推进,雨滴声清晰。",
  "duration": 8,
  "resolution": "720P",
  "ratio": "16:9",
  "audio": true,
  "watermark": false
}), signal: AbortSignal.timeout(120000) });
if (!response.ok) throw new Error(await response.text());
const result = await response.json();
if (result?.success === false || result?.code === false || result?.error) throw new Error(JSON.stringify(result));
console.log(JSON.stringify(result, null, 2));

First-to-last frame

Applies to: wan3.0-video

POST /v1/videos

{
  "model": "wan3.0-video",
  "prompt": "镜头从近景逐渐拉远,自然过渡到尾帧。",
  "first_frame": "https://example.com/subject.png",
  "last_frame": "https://example.com/end.png",
  "duration": 6,
  "resolution": "720P"
}

curl

curl --fail-with-body --silent --show-error --connect-timeout 10 --max-time 120 --request POST 'https://api.tu-zi.com/v1/videos' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "wan3.0-video",
  "prompt": "镜头从近景逐渐拉远,自然过渡到尾帧。",
  "first_frame": "https://example.com/subject.png",
  "last_frame": "https://example.com/end.png",
  "duration": 6,
  "resolution": "720P"
}'

python

import json
import os
import requests

url = "https://api.tu-zi.com/v1/videos"
headers = json.loads("{\"Authorization\":\"Bearer YOUR_API_KEY\",\"Content-Type\":\"application/json\"}")
for name in ["API_KEY"]:
    if not os.environ.get(name, "").strip():
        raise RuntimeError("Set environment variable: " + name)
headers["Authorization"] = "Bearer " + os.environ["API_KEY"]
payload = json.loads("{\"model\":\"wan3.0-video\",\"prompt\":\"镜头从近景逐渐拉远,自然过渡到尾帧。\",\"first_frame\":\"https://example.com/subject.png\",\"last_frame\":\"https://example.com/end.png\",\"duration\":6,\"resolution\":\"720P\"}")
response = requests.request("POST", url, headers=headers, json=payload, timeout=120)
response.raise_for_status()
result = response.json()
if isinstance(result, dict) and (result.get("success") is False or result.get("code") is False or result.get("error")):
    raise RuntimeError(json.dumps(result, ensure_ascii=False))
print(json.dumps(result, ensure_ascii=False, indent=2))

javascript

// Node.js 20+
const url = "https://api.tu-zi.com/v1/videos";
const headers = {
  "Authorization": "Bearer YOUR_API_KEY",
  "Content-Type": "application/json"
};
for (const name of ["API_KEY"]) {
  if (!process.env[name]?.trim()) throw new Error("Set environment variable: " + name);
}
headers.Authorization = 'Bearer ' + process.env.API_KEY;
const response = await fetch(url, { method: "POST", headers, body: JSON.stringify({
  "model": "wan3.0-video",
  "prompt": "镜头从近景逐渐拉远,自然过渡到尾帧。",
  "first_frame": "https://example.com/subject.png",
  "last_frame": "https://example.com/end.png",
  "duration": 6,
  "resolution": "720P"
}), signal: AbortSignal.timeout(120000) });
if (!response.ok) throw new Error(await response.text());
const result = await response.json();
if (result?.success === false || result?.code === false || result?.error) throw new Error(JSON.stringify(result));
console.log(JSON.stringify(result, null, 2));

Character and motion

Applies to: wan3.0-video

POST /v1/videos

{
  "model": "wan3.0-video",
  "prompt": "图片1中的人物模仿视频1中的动作。",
  "reference_images": [
    "https://example.com/subject.png"
  ],
  "reference_videos": [
    "https://example.com/action.mp4"
  ],
  "duration": 8,
  "resolution": "720P"
}

curl

curl --fail-with-body --silent --show-error --connect-timeout 10 --max-time 120 --request POST 'https://api.tu-zi.com/v1/videos' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "wan3.0-video",
  "prompt": "图片1中的人物模仿视频1中的动作。",
  "reference_images": [
    "https://example.com/subject.png"
  ],
  "reference_videos": [
    "https://example.com/action.mp4"
  ],
  "duration": 8,
  "resolution": "720P"
}'

python

import json
import os
import requests

url = "https://api.tu-zi.com/v1/videos"
headers = json.loads("{\"Authorization\":\"Bearer YOUR_API_KEY\",\"Content-Type\":\"application/json\"}")
for name in ["API_KEY"]:
    if not os.environ.get(name, "").strip():
        raise RuntimeError("Set environment variable: " + name)
headers["Authorization"] = "Bearer " + os.environ["API_KEY"]
payload = json.loads("{\"model\":\"wan3.0-video\",\"prompt\":\"图片1中的人物模仿视频1中的动作。\",\"reference_images\":[\"https://example.com/subject.png\"],\"reference_videos\":[\"https://example.com/action.mp4\"],\"duration\":8,\"resolution\":\"720P\"}")
response = requests.request("POST", url, headers=headers, json=payload, timeout=120)
response.raise_for_status()
result = response.json()
if isinstance(result, dict) and (result.get("success") is False or result.get("code") is False or result.get("error")):
    raise RuntimeError(json.dumps(result, ensure_ascii=False))
print(json.dumps(result, ensure_ascii=False, indent=2))

javascript

// Node.js 20+
const url = "https://api.tu-zi.com/v1/videos";
const headers = {
  "Authorization": "Bearer YOUR_API_KEY",
  "Content-Type": "application/json"
};
for (const name of ["API_KEY"]) {
  if (!process.env[name]?.trim()) throw new Error("Set environment variable: " + name);
}
headers.Authorization = 'Bearer ' + process.env.API_KEY;
const response = await fetch(url, { method: "POST", headers, body: JSON.stringify({
  "model": "wan3.0-video",
  "prompt": "图片1中的人物模仿视频1中的动作。",
  "reference_images": [
    "https://example.com/subject.png"
  ],
  "reference_videos": [
    "https://example.com/action.mp4"
  ],
  "duration": 8,
  "resolution": "720P"
}), signal: AbortSignal.timeout(120000) });
if (!response.ok) throw new Error(await response.text());
const result = await response.json();
if (result?.success === false || result?.code === false || result?.error) throw new Error(JSON.stringify(result));
console.log(JSON.stringify(result, null, 2));

Character and audio

Applies to: wan3.0-video

POST /v1/videos

Contract checked; the 2026-11-15 main-site audio-reference test failed on media download. Confirm generation-service access; do not automatically retry creation.

{
  "model": "wan3.0-video",
  "prompt": "图片1中的人物用音频1的声音说话。",
  "reference_images": [
    "https://example.com/subject.png"
  ],
  "reference_audio": [
    "https://example.com/voice.wav"
  ],
  "audio": true,
  "duration": 8,
  "resolution": "720P"
}

Reference video edit

Applies to: wan3.0-video

POST /v1/videos

{
  "model": "wan3.0-video",
  "prompt": "保持视频1的动作和镜头,把背景改为雪山。",
  "reference_videos": [
    "https://example.com/action.mp4"
  ],
  "duration": 8,
  "resolution": "720P",
  "prompt_extend": true
}

curl

curl --fail-with-body --silent --show-error --connect-timeout 10 --max-time 120 --request POST 'https://api.tu-zi.com/v1/videos' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "wan3.0-video",
  "prompt": "保持视频1的动作和镜头,把背景改为雪山。",
  "reference_videos": [
    "https://example.com/action.mp4"
  ],
  "duration": 8,
  "resolution": "720P",
  "prompt_extend": true
}'

python

import json
import os
import requests

url = "https://api.tu-zi.com/v1/videos"
headers = json.loads("{\"Authorization\":\"Bearer YOUR_API_KEY\",\"Content-Type\":\"application/json\"}")
for name in ["API_KEY"]:
    if not os.environ.get(name, "").strip():
        raise RuntimeError("Set environment variable: " + name)
headers["Authorization"] = "Bearer " + os.environ["API_KEY"]
payload = json.loads("{\"model\":\"wan3.0-video\",\"prompt\":\"保持视频1的动作和镜头,把背景改为雪山。\",\"reference_videos\":[\"https://example.com/action.mp4\"],\"duration\":8,\"resolution\":\"720P\",\"prompt_extend\":true}")
response = requests.request("POST", url, headers=headers, json=payload, timeout=120)
response.raise_for_status()
result = response.json()
if isinstance(result, dict) and (result.get("success") is False or result.get("code") is False or result.get("error")):
    raise RuntimeError(json.dumps(result, ensure_ascii=False))
print(json.dumps(result, ensure_ascii=False, indent=2))

javascript

// Node.js 20+
const url = "https://api.tu-zi.com/v1/videos";
const headers = {
  "Authorization": "Bearer YOUR_API_KEY",
  "Content-Type": "application/json"
};
for (const name of ["API_KEY"]) {
  if (!process.env[name]?.trim()) throw new Error("Set environment variable: " + name);
}
headers.Authorization = 'Bearer ' + process.env.API_KEY;
const response = await fetch(url, { method: "POST", headers, body: JSON.stringify({
  "model": "wan3.0-video",
  "prompt": "保持视频1的动作和镜头,把背景改为雪山。",
  "reference_videos": [
    "https://example.com/action.mp4"
  ],
  "duration": 8,
  "resolution": "720P",
  "prompt_extend": true
}), signal: AbortSignal.timeout(120000) });
if (!response.ok) throw new Error(await response.text());
const result = await response.json();
if (result?.success === false || result?.code === false || result?.error) throw new Error(JSON.stringify(result));
console.log(JSON.stringify(result, null, 2));

Document to video

Applies to: wan3.0-video

POST /v1/videos

{
  "model": "wan3.0-video",
  "prompt": "根据文件内容制作产品讲解视频。",
  "file": "https://example.com/brief.pdf",
  "prompt_extend": true,
  "duration": 10,
  "resolution": "720P"
}

curl

curl --fail-with-body --silent --show-error --connect-timeout 10 --max-time 120 --request POST 'https://api.tu-zi.com/v1/videos' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "wan3.0-video",
  "prompt": "根据文件内容制作产品讲解视频。",
  "file": "https://example.com/brief.pdf",
  "prompt_extend": true,
  "duration": 10,
  "resolution": "720P"
}'

python

import json
import os
import requests

url = "https://api.tu-zi.com/v1/videos"
headers = json.loads("{\"Authorization\":\"Bearer YOUR_API_KEY\",\"Content-Type\":\"application/json\"}")
for name in ["API_KEY"]:
    if not os.environ.get(name, "").strip():
        raise RuntimeError("Set environment variable: " + name)
headers["Authorization"] = "Bearer " + os.environ["API_KEY"]
payload = json.loads("{\"model\":\"wan3.0-video\",\"prompt\":\"根据文件内容制作产品讲解视频。\",\"file\":\"https://example.com/brief.pdf\",\"prompt_extend\":true,\"duration\":10,\"resolution\":\"720P\"}")
response = requests.request("POST", url, headers=headers, json=payload, timeout=120)
response.raise_for_status()
result = response.json()
if isinstance(result, dict) and (result.get("success") is False or result.get("code") is False or result.get("error")):
    raise RuntimeError(json.dumps(result, ensure_ascii=False))
print(json.dumps(result, ensure_ascii=False, indent=2))

javascript

// Node.js 20+
const url = "https://api.tu-zi.com/v1/videos";
const headers = {
  "Authorization": "Bearer YOUR_API_KEY",
  "Content-Type": "application/json"
};
for (const name of ["API_KEY"]) {
  if (!process.env[name]?.trim()) throw new Error("Set environment variable: " + name);
}
headers.Authorization = 'Bearer ' + process.env.API_KEY;
const response = await fetch(url, { method: "POST", headers, body: JSON.stringify({
  "model": "wan3.0-video",
  "prompt": "根据文件内容制作产品讲解视频。",
  "file": "https://example.com/brief.pdf",
  "prompt_extend": true,
  "duration": 10,
  "resolution": "720P"
}), signal: AbortSignal.timeout(120000) });
if (!response.ok) throw new Error(await response.text());
const result = await response.json();
if (result?.success === false || result?.code === false || result?.error) throw new Error(JSON.stringify(result));
console.log(JSON.stringify(result, null, 2));

Webpage to portrait video

Applies to: wan3.0-video

POST /v1/videos

{
  "model": "wan3.0-video",
  "prompt": "根据网页内容制作竖屏产品介绍。",
  "link": "https://example.com/product",
  "prompt_extend": true,
  "ratio": "9:16",
  "resolution": "720P",
  "duration": 8
}

curl

curl --fail-with-body --silent --show-error --connect-timeout 10 --max-time 120 --request POST 'https://api.tu-zi.com/v1/videos' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "wan3.0-video",
  "prompt": "根据网页内容制作竖屏产品介绍。",
  "link": "https://example.com/product",
  "prompt_extend": true,
  "ratio": "9:16",
  "resolution": "720P",
  "duration": 8
}'

python

import json
import os
import requests

url = "https://api.tu-zi.com/v1/videos"
headers = json.loads("{\"Authorization\":\"Bearer YOUR_API_KEY\",\"Content-Type\":\"application/json\"}")
for name in ["API_KEY"]:
    if not os.environ.get(name, "").strip():
        raise RuntimeError("Set environment variable: " + name)
headers["Authorization"] = "Bearer " + os.environ["API_KEY"]
payload = json.loads("{\"model\":\"wan3.0-video\",\"prompt\":\"根据网页内容制作竖屏产品介绍。\",\"link\":\"https://example.com/product\",\"prompt_extend\":true,\"ratio\":\"9:16\",\"resolution\":\"720P\",\"duration\":8}")
response = requests.request("POST", url, headers=headers, json=payload, timeout=120)
response.raise_for_status()
result = response.json()
if isinstance(result, dict) and (result.get("success") is False or result.get("code") is False or result.get("error")):
    raise RuntimeError(json.dumps(result, ensure_ascii=False))
print(json.dumps(result, ensure_ascii=False, indent=2))

javascript

// Node.js 20+
const url = "https://api.tu-zi.com/v1/videos";
const headers = {
  "Authorization": "Bearer YOUR_API_KEY",
  "Content-Type": "application/json"
};
for (const name of ["API_KEY"]) {
  if (!process.env[name]?.trim()) throw new Error("Set environment variable: " + name);
}
headers.Authorization = 'Bearer ' + process.env.API_KEY;
const response = await fetch(url, { method: "POST", headers, body: JSON.stringify({
  "model": "wan3.0-video",
  "prompt": "根据网页内容制作竖屏产品介绍。",
  "link": "https://example.com/product",
  "prompt_extend": true,
  "ratio": "9:16",
  "resolution": "720P",
  "duration": 8
}), signal: AbortSignal.timeout(120000) });
if (!response.ok) throw new Error(await response.text());
const result = await response.json();
if (result?.success === false || result?.code === false || result?.error) throw new Error(JSON.stringify(result));
console.log(JSON.stringify(result, null, 2));

Seed and silent output

Applies to: wan3.0-video

POST /v1/videos

{
  "model": "wan3.0-video",
  "prompt": "同一机位拍摄一只白兔走过草地。",
  "duration": 5,
  "resolution": "480P",
  "ratio": "16:9",
  "seed": 0,
  "audio": false,
  "watermark": false
}

curl

curl --fail-with-body --silent --show-error --connect-timeout 10 --max-time 120 --request POST 'https://api.tu-zi.com/v1/videos' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "wan3.0-video",
  "prompt": "同一机位拍摄一只白兔走过草地。",
  "duration": 5,
  "resolution": "480P",
  "ratio": "16:9",
  "seed": 0,
  "audio": false,
  "watermark": false
}'

python

import json
import os
import requests

url = "https://api.tu-zi.com/v1/videos"
headers = json.loads("{\"Authorization\":\"Bearer YOUR_API_KEY\",\"Content-Type\":\"application/json\"}")
for name in ["API_KEY"]:
    if not os.environ.get(name, "").strip():
        raise RuntimeError("Set environment variable: " + name)
headers["Authorization"] = "Bearer " + os.environ["API_KEY"]
payload = json.loads("{\"model\":\"wan3.0-video\",\"prompt\":\"同一机位拍摄一只白兔走过草地。\",\"duration\":5,\"resolution\":\"480P\",\"ratio\":\"16:9\",\"seed\":0,\"audio\":false,\"watermark\":false}")
response = requests.request("POST", url, headers=headers, json=payload, timeout=120)
response.raise_for_status()
result = response.json()
if isinstance(result, dict) and (result.get("success") is False or result.get("code") is False or result.get("error")):
    raise RuntimeError(json.dumps(result, ensure_ascii=False))
print(json.dumps(result, ensure_ascii=False, indent=2))

javascript

// Node.js 20+
const url = "https://api.tu-zi.com/v1/videos";
const headers = {
  "Authorization": "Bearer YOUR_API_KEY",
  "Content-Type": "application/json"
};
for (const name of ["API_KEY"]) {
  if (!process.env[name]?.trim()) throw new Error("Set environment variable: " + name);
}
headers.Authorization = 'Bearer ' + process.env.API_KEY;
const response = await fetch(url, { method: "POST", headers, body: JSON.stringify({
  "model": "wan3.0-video",
  "prompt": "同一机位拍摄一只白兔走过草地。",
  "duration": 5,
  "resolution": "480P",
  "ratio": "16:9",
  "seed": 0,
  "audio": false,
  "watermark": false
}), signal: AbortSignal.timeout(120000) });
if (!response.ok) throw new Error(await response.text());
const result = await response.json();
if (result?.success === false || result?.code === false || result?.error) throw new Error(JSON.stringify(result));
console.log(JSON.stringify(result, null, 2));

Task results and downloads

Save id or task_id from submission. Poll GET /v1/videos/{task_id}: queued / in_progress lead to completed or failed. Read video_url on completion (some responses also expose metadata.url). Resolve relative URLs against the API origin. The site /content endpoint uses your site key; external downloads must not receive that key. Download expiring results promptly. Resume GET after a timeout rather than automatically repeating POST.

Complete unified video Python / JavaScript polling and download examples

Troubleshooting

SymptomCheck
Image validation / URI errorEnsure a video or task ID was not placed in an image field; check the URL returns media
Unsupported content type / fieldCheck the exact family and content/contents/input schema; voice_id cannot be an audio URL
400 conflicting fieldsCheck prompt/input, frames/references, and seconds/response_format exclusivity
HTTP success but task failedRetain the site task ID, time, model, domain and redacted request; submission 200 is not output success
404 or inaccessible taskCheck domain, key access and task type; do not use IDs from another site or the official API
Local file cannot be fetchedUse a supported upload flow or a reachable HTTPS media URL

Sources and scope

Wan 3.0 API

Use cases

  • Choose video models and media formats
  • Diagnose request and task failures

API protocols

  • /v1/videos

FAQ

Does a task ID prove generation succeeded?

No. Save the site task ID, poll to a successful terminal state and verify the result. Inspect failures instead of automatically creating a new task.

Can I put a local image, video or WAV path in JSON?

No. URL fields require reachable media, not localhost, disk paths or browser-login links. Kling PCM WAV requires an enabled multipart voice endpoint (both sites returned 404 on 2026-11-15). Follow each family’s asset workflow for other media.

Can parameters and task IDs be reused across models?

Do not assume compatibility. Check the exact model, endpoint, casing, media role and exclusive fields. Editing, drafts and voices require accessible successful tasks of the correct kind. Official capabilities are not evidence of site acceptance.

Official sources

  1. Wan 3.0 API Official