API reference
Callbacks: Get Notified When a Video Is Ready
Instead of polling, pass callback_url when you create a task. When the render succeeds or fails, we POST the task object to that URL.
Get API keyBy the Wan 3 API team ·
Callbacks: Get Notified When a Video Is Ready
Instead of polling, pass callback_url when you create a task. When the render succeeds or fails, we POST the task object to that URL.
curl -X POST "https://api.wan3api.org/v1/videos/generations" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"model": "wan-3",
"prompt": "A red fox runs through fresh snow at sunrise, slow motion, cinematic",
"duration": 5,
"resolution": "480P",
"aspect_ratio": "16:9",
"callback_url": "https://your-app.com/webhooks/video"
}'Payload
A JSON task object, the same one GET /tasks/:id returns, with Content-Type: application/json and an X-Task-Id header.
json
{
"id": "3f1c9a52-6d1e-4c1b-9a77-2f4d8f0c9e10",
"object": "video.generation",
"model": "wan-3",
"mode": "text",
"status": "succeeded",
"progress": 100,
"prompt": "A red fox runs through fresh snow at sunrise, slow motion, cinematic",
"duration": 5,
"resolution": "480P",
"aspect_ratio": "16:9",
"video_url": "https://api.wan3api.org/api/video/media/video/outputs/…/3f1c9a52.mp4",
"credits": 15,
"refunded": false,
"error": null,
"source": "api",
"created_at": "2026-11-01T08:00:00.000Z",
"completed_at": "2026-11-01T08:00:41.000Z"
}Delivery and retries
Answer with any 2xx within 10 seconds. On a timeout or 5xx we try 3 times in all; a 4xx stops retries. Each task is delivered once at most, so keep polling as a fallback.
Verify before you trust it
Callbacks aren't signed. Treat the body as a hint: read the task id, then call GET /tasks/:id with your key and act on that response.
javascript
// Express: confirm the task with your key before acting on it.
app.post("/webhooks/video", express.json(), async (req, res) => {
res.sendStatus(200);
const response = await fetch(`https://api.wan3api.org/v1/tasks/${req.body.id}`, {
headers: { Authorization: `Bearer ${process.env.API_KEY}` },
});
const task = await response.json();
if (task.status === "succeeded") await saveVideo(task.id, task.video_url);
});