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.
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
| Media | Fields | Encoding and transport | Preparation and limits |
|---|---|---|---|
| Images / frames | input_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 video | reference_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 audio | reference_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 / webpage | file / link | Public 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.
| Field | Type | Use and constraints |
|---|---|---|
Authorization | header string | Required: Bearer <site API key>, with Content-Type: application/json. Provider credentials and regional endpoints are managed by the service. |
model | string | Required: wan3.0-video. The official prime variant is not established as available here. |
prompt | string | Maps to input.prompt. Supply prompt or media; official limit 20,000 characters. Number image, video and audio references separately. |
first_frame | string | First image URL, mapped to input.media with type=first_frame; at most one. |
last_frame | string | Last image, mapped to type=last_frame; one at most, requires a first frame and excludes reference media. |
reference_images | string[] | 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_videos | string[] | Maps to reference_video; up to 5 clips, 1–15s each, total ≤15s, ≤100 MB each. Use reachable media URLs. |
reference_audio | string[] | Maps to reference_audio; up to 5 clips, 1–15s each, total ≤15s, ≤15 MB each. See the known download failure above. |
file | string | Maps to type=file; one public document URL, mutually exclusive with link; requires prompt_extend=true. |
link | string | Maps to type=link; one public web page without login, excludes file and requires prompt_extend=true. |
duration | integer | Maps to parameters.duration; optional, default 5; 2–30s or -1 automatic. Input plus output video must total ≤30s. |
resolution | string | Maps to parameters.resolution: 480P/720P/1080P. Official default 1080P; site routes may set defaults, so specify it explicitly. |
ratio | string | Maps to parameters.ratio: adaptive/21:9/16:9/4:3/1:1/3:4/9:16. Official default adaptive; recommended for frames and editing. |
audio | boolean | Maps to parameters.audio; optional, default true; false removes audio without changing the official sound-toggle price. |
watermark | boolean | Maps to parameters.watermark; optional, default false; explicit false is preserved. |
prompt_extend | boolean | Maps to parameters.prompt_extend; optional, default true; rewriting can add latency and is required with file/link. |
seed | integer | Maps to parameters.seed; optional, -1 or 0–2147483647; random by default. Reproducibility is not guaranteed. |
input_reference / seconds / size | site aliases | Site aliases for first frame, duration and pixel size. Prefer the canonical fields above without duplicating a setting. |
input / input.media[].type / input.media[].url | official object | Official 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-Async | official header | Official 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
| Symptom | Check |
|---|---|
| Image validation / URI error | Ensure a video or task ID was not placed in an image field; check the URL returns media |
| Unsupported content type / field | Check the exact family and content/contents/input schema; voice_id cannot be an audio URL |
| 400 conflicting fields | Check prompt/input, frames/references, and seconds/response_format exclusivity |
| HTTP success but task failed | Retain the site task ID, time, model, domain and redacted request; submission 200 is not output success |
| 404 or inaccessible task | Check domain, key access and task type; do not use IDs from another site or the official API |
| Local file cannot be fetched | Use a supported upload flow or a reachable HTTPS media URL |
Sources and scope
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.
Related guides
Official sources
- Wan 3.0 API Official
兔子API