Alibaba Wan 3.0 Video API: старт работы с видеогенерацией нового поколения
Целевая модель:
wan3.0-video(необязательный сестринский ID:wan3.0-video-prime)
Эндпоинт инференса:https://api.toapis.com/v1/videos/generations
Связанные материалы: Wan 3.0 Prime против Wan 2.6 Flash · Непрерывность длинного видео Kling Video O1 · Справка Wan 3.0 · Model guide wan3.0-video · Model guide wan3.0-video-prime
1. Кратко и обзор возможностей
- Сначала каталог: в черновиках планирования иногда пишут
wan-3-prime. Эта строка не является документированным публичным ID. Проверка 2026-11-20 официальной справки генерации Wan 3.0 (HTTP 200) перечисляетwan3.0-videoиwan3.0-video-prime. Обе модели используют один и тот же All-in-One API на этой странице. Отдельного пути документации только для Prime не было. - Контракт: асинхронно отправляйте на
POST /v1/videos/generations, затем опрашивайтеGET /v1/videos/generations/{id}доcompletedилиfailed. Обычные задачи можно также запрашивать черезGET /v1/tasks/{id}. Официальные примеры используютhttps://toapis.com(для материкового Китая —https://toapis.cn). Другие руководства этой серии используютhttps://api.toapis.com. Выберите один origin и придерживайтесь его. - Несколько режимов на одной схеме: текст в видео; управление первым кадром или первым и последним; совместная генерация с опорными изображениями, видео и аудио; один файл или публичная веб-страница; редактирование или продление по опорному клипу. Режим первого и последнего кадра и режим опорных активов взаимно исключают друг друга.
- Медиа: отправляйте только публичные URL
http://илиhttps://. Локальные файлы сначала загрузите и используйте возвращённый URL. Не отправляйте base64 или локальные пути. Требуется хотя бы одно из двух:promptили медиаактивы. - Непроверенные утверждения, которые нужно отбросить: черновые цены вроде
$0.150за 5 секунд не являются текущей документацией ToAPIs. Подтверждайте живые ставки и поддержку канала в аккаунте.
2. Официальные ID Wan 3.0, параметры и правила сочетания
В поле model используйте одно из двух публичных имён модели. Не подставляйте черновой псевдоним и не изобретайте флаг режима Prime.
| ID каталога | Роль в этом руководстве | Документированные задачи |
|---|---|---|
wan3.0-video | ID по умолчанию / стандартный All-in-One | Текст в видео, первый и последний кадры, мультимодальные ссылки, файл или ссылка, правка и продление |
wan3.0-video-prime | Сестринский ID Prime на той же схеме | Та же структура запроса, что у wan3.0-video; выбирайте его только если он есть в каталоге и вам нужен SKU Prime |
wan2.6 | Связанный более ранний ID Wan; см. справку генерации Wan 2.6 | Текст в видео, изображение в видео и опорное видео на другой карте параметров (без 480p; длительность 5/10/15) |
Основные поля запроса (общие для обоих ID Wan 3.0):
| Поле | Документированные значения | Примечания |
|---|---|---|
prompt | Строка | Содержание, движение, камера и звук. Нужно хотя бы одно из двух: prompt или медиаактивы. Ссылайтесь на активы как на «image 1», «video 1», «audio 1» в порядке массива |
duration | Целые 2–30 или -1 | По умолчанию 5. -1 — умная длительность: модель выбирает длину |
ratio | adaptive (по умолчанию), 16:9, 9:16, 1:1, 4:3, 3:4 | aspect_ratio — совместимый псевдоним; не передавайте оба |
resolution | 480p, 720p, 1080p (по умолчанию 1080p) | Все три значения документированы в этом контракте |
audio | Булево, по умолчанию true | Аудио включено по умолчанию |
watermark | Булево, по умолчанию false | По умолчанию выключено |
prompt_extend | Булево, по умолчанию true | Переписывание LLM улучшает короткие промпты и добавляет задержку; поставьте false, чтобы использовать промпт дословно |
seed | Необязательное целое | Те же параметры плюс seed помогают воспроизвести похожий результат |
image_with_roles | Массив {url, role} | role — first_frame или last_frame. Не более одного каждого; last_frame требует first_frame |
reference_images | До 10 публичных URL изображений | Нельзя смешивать с первым и последним кадрами |
video_list | До 5 клипов, суммарная длительность ≤15 с | Каждый элемент — {"video_url": "..."} |
audio_with_roles | До 5 клипов, сумма ≤15 с | Каждый элемент — {url, role: "reference_audio"} |
metadata.media | Один file или одна link | {type, url}. Файл и ссылку нельзя сочетать и нельзя смешивать с режимом первого и последнего кадра |
disable_nsfw | Булево, по умолчанию true | Платформенный параметр ToAPIs, не пересылается апстриму. Только явное JSON false включает запасной канал, если аккаунт и регион продаж это допускают; в материковом Китае он всегда выключен |
Правила сочетания активов из официальной таблицы:
| Содержимое запроса | Поддерживается? | Примечания |
|---|---|---|
| Только промпт | Да | Текст в видео |
| Только первый кадр | Да | Управление первым кадром |
| Первый и последний кадр | Да | Последний кадр нельзя использовать отдельно |
| Опорные изображения и опорные видео | Да | Можно сочетать, в том числе с опорным аудио |
| Первый кадр и опорное видео | Нет | Режим первого и последнего кадра и режим опорных активов взаимно исключают друг друга |
| Файл и веб-ссылка | Нет | Взаимно исключают друг друга |
Если API возвращает сообщение вроде «Wan 3.0 cannot mix first/last frames with reference assets/files/web pages in the same request», уберите одно из двух семейств и отправьте запрос снова.
Редактирование видео — путь, классифицируемый по промпту, а не отдельный эндпоинт: включите намерение правки (например, “edit the video”, “remove”, “replace”) и передайте опорный клип. Такие задания требуют ratio равного adaptive и duration равного -1, а вход должен быть 4–30 секунд. Продление использует формулировки вроде “extend” или “continue”, а duration ставят в -1 или в длину источника плюс продление (всего ≤ 30 секунд).

Рисунок 1: документированная нагрузка Wan 3.0 отправляется на POST /v1/videos/generations; опрашивайте тот же идентификатор задачи и читайте result.data[0].url только после status completed.
Для сравнения возможностей и стоимости с Wan 2.6 Flash см. Wan 3.0 Prime против Wan 2.6 Flash. Для длинной непрерывности в другом семействе с окном 3–10 секунд см. руководство Kling Video O1.
3. Производственная реализация: cURL и Python
Международные примеры этой серии используют https://api.toapis.com. Официальная документация указывает пользователям материкового Китая https://toapis.cn. Оставляйте один origin на среду.
Шаг 1. Отправка текста в видео через cURL
curl --request POST \
--url https://api.toapis.com/v1/videos/generations \
--header "Authorization: Bearer $TOAPIS_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"model": "wan3.0-video",
"prompt": "An orange cat running through the streets of Tokyo after rain, cinematic camera work",
"duration": 5,
"ratio": "16:9",
"resolution": "1080p",
"audio": true,
"watermark": false
}'
Запрос с первым и последним кадром использует image_with_roles и не должен содержать опорные медиа, файлы или ссылки:
curl --request POST \
--url https://api.toapis.com/v1/videos/generations \
--header "Authorization: Bearer $TOAPIS_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"model": "wan3.0-video",
"prompt": "The camera pushes in naturally as the person transitions from standing to smiling and waving",
"duration": 8,
"ratio": "adaptive",
"resolution": "1080p",
"image_with_roles": [
{"url": "https://example.com/first-frame.png", "role": "first_frame"},
{"url": "https://example.com/last-frame.png", "role": "last_frame"}
]
}'
Шаг 2. Помощник и опросчик на Python
Фрагмент следует документированному пути статуса задачи и состояниям queued / in_progress / completed / failed. Перед выпуском сверьте id, result.data[0].url и конверт ответа со справкой API для вашего аккаунта.
import os
import time
import requests
API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
ENDPOINT = f"{BASE}/v1/videos/generations"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
DOCUMENTED_IDS = {"wan3.0-video", "wan3.0-video-prime"}
RATIOS = {"adaptive", "16:9", "9:16", "1:1", "4:3", "3:4"}
RESOLUTIONS = {"480p", "720p", "1080p"}
def dispatch_wan30(
prompt: str | None = None,
*,
model: str = "wan3.0-video",
duration: int = 5,
ratio: str = "16:9",
resolution: str = "1080p",
audio: bool = True,
watermark: bool = False,
prompt_extend: bool | None = None,
image_with_roles: list[dict] | None = None,
reference_images: list[str] | None = None,
video_list: list[dict] | None = None,
audio_with_roles: list[dict] | None = None,
media: list[dict] | None = None,
) -> str:
if model not in DOCUMENTED_IDS:
raise ValueError("Send wan3.0-video or wan3.0-video-prime; wan-3-prime is not a documented public ID")
if duration != -1 and duration not in range(2, 31):
raise ValueError("duration must be 2–30 or -1")
if ratio not in RATIOS:
raise ValueError("unsupported ratio")
if resolution not in RESOLUTIONS:
raise ValueError("resolution must be 480p, 720p, or 1080p")
roles = [item.get("role") for item in (image_with_roles or [])]
if "last_frame" in roles and "first_frame" not in roles:
raise ValueError("last_frame requires first_frame")
has_frames = bool(image_with_roles)
has_refs = any([reference_images, video_list, audio_with_roles, media])
if has_frames and has_refs:
raise ValueError("first/last-frame mode cannot mix with reference assets, files, or links")
if media and len(media) > 1:
raise ValueError("a single request accepts at most one file or one web page")
if media and len({item.get("type") for item in media}) > 1:
raise ValueError("file and link cannot be used together")
if not prompt and not has_frames and not has_refs:
raise ValueError("provide a prompt or at least one media asset")
if reference_images and len(reference_images) > 10:
raise ValueError("reference_images is documented as at most 10")
if video_list and len(video_list) > 5:
raise ValueError("video_list is documented as at most 5 clips")
if audio_with_roles and len(audio_with_roles) > 5:
raise ValueError("audio_with_roles is documented as at most 5 clips")
payload: dict = {
"model": model,
"duration": duration,
"ratio": ratio,
"resolution": resolution,
"audio": audio,
"watermark": watermark,
}
if prompt:
payload["prompt"] = prompt
if prompt_extend is not None:
payload["prompt_extend"] = prompt_extend
if image_with_roles:
payload["image_with_roles"] = image_with_roles
if reference_images:
payload["reference_images"] = reference_images
if video_list:
payload["video_list"] = video_list
if audio_with_roles:
payload["audio_with_roles"] = audio_with_roles
if media:
payload["metadata"] = {"media": media}
res = requests.post(ENDPOINT, headers=HEADERS, json=payload, timeout=30)
res.raise_for_status()
data = res.json()
task_id = data.get("id") or data.get("task_id")
if not task_id:
raise RuntimeError(f"Unexpected submission envelope: {data}")
return task_id
def poll_task(task_id: str, deadline_s: int = 900) -> str:
poll_url = f"{BASE}/v1/videos/generations/{task_id}"
interval = 10.0
start = time.time()
time.sleep(5)
while time.time() - start < deadline_s:
poll = requests.get(poll_url, headers=HEADERS, timeout=15)
if poll.status_code == 429:
retry_after = poll.headers.get("Retry-After")
time.sleep(float(retry_after) if retry_after else min(interval * 2, 120))
continue
poll.raise_for_status()
data = poll.json()
status = data.get("status")
if status == "completed":
return data["result"]["data"][0]["url"]
if status == "failed":
raise RuntimeError(f"Generation failed: {data.get('error')}")
time.sleep(interval)
interval = min(interval * 1.5, 30.0)
raise TimeoutError(f"Task {task_id} exceeded {deadline_s}s; check status before retrying")
if __name__ == "__main__":
task_id = dispatch_wan30(
"An orange cat running through the streets of Tokyo after rain, cinematic camera work",
duration=5,
ratio="16:9",
resolution="1080p",
)
print("Task:", task_id)
print("Video:", poll_task(task_id))
Храните версию шаблона промпта рядом с записью задачи, чтобы отличать смену параметров от смены формулировки. Скачивайте файл до expires_at; справка о статусе документирует 30-дневное окно хранения. Если включён prompt_extend (это значение по умолчанию), на коротких промптах возможна дополнительная задержка — официальная страница описывает это качественно и не публикует измеренную величину.
4. Обработка ошибок и матрица статусов
Категории ниже — отправная точка диагностики, а не гарантия точных кодов ошибок ToAPIs. Успешный HTTP-запрос всё равно требует читать status задачи. См. справочник ошибок для ошибок запроса и причин status: failed, таких как content_policy_rejected, insufficient_user_balance, generation_timeout или video_edit_parameters_required.
| HTTP или состояние задачи | Частая категория | Рекомендуемое действие |
|---|---|---|
400 | Недопустимое поле, смешение первого и последнего кадров с опорными активами, одновременно ratio и aspect_ratio или файл плюс ссылка | Подтвердите wan3.0-video или wan3.0-video-prime, уберите одно из исключающих семейств и используйте только публичные URL |
401 | Отсутствующий или недействительный API-ключ | Смените ключ в панели ToAPIs и проверьте заголовок Authorization: Bearer |
429 | Ограничение частоты или параллелизма | Соблюдайте Retry-After, если он есть; отступайте с джиттером; повторяйте только когда это безопасно |
5xx или тайм-аут клиента | Временная проблема шлюза или апстрима | Запросите существующий идентификатор задачи до повторной отправки |
status: queued или in_progress | Это не ошибка | Подождите и опросите снова; prompt_extend может увеличить задержку |
status: failed с video_edit_parameters_required | Не выполнены ограничения редактирования | Задайте ratio равным adaptive, duration равным -1 и используйте источник 4–30 секунд |
status: failed (прочее) | Генерация не удалась | Читайте error.code и error.message (и error.reason, если есть). Не повторяйте неизменённую нагрузку, отклонённую политикой |
5. Цены и FinOps
Справка генерации Wan 3.0 не публикует долларовую или кредитную таблицу. Выгрузка страниц model-guide от 2026-11-20 показала ценовой ориентир 26.3 credits / секунду для wan3.0-video и 41.14 credits / секунду для wan3.0-video-prime; обе страницы указали, что итоговая тарификация следует текущей котировке аккаунта и текущим правилам длительности и разрешения. Считайте эти кредитные цифры снимком, а не контрактом для каждого разрешения или режима. Не переводите кредиты в валюту самостоятельно и не используйте черновые долларовые ставки.
- Начинайте с
wan3.0-videoна средней длительности, например 5 секунд, и повышайте разрешение или переходите на Prime только после того, как промпт и сочетание активов стабилизируются. - Умная длительность (
-1) иprompt_extendменяют объём работы модели. Это документированные возможности, а не повод предполагать фиксированную цену или задержку задания. - Отображаемая цена — не гарантия канала. Перед прогнозом пакета подтвердите ID и живую котировку через
GET /v1/models?type=videoи каталог аккаунта.
6. Часто задаваемые вопросы
См. блок FAQ во frontmatter. Кратко: отправляйте wan3.0-video или wan3.0-video-prime, а не wan-3-prime; первый и последний кадры нельзя смешивать с опорными активами; длительность — 2–30 секунд или -1; для правки нужны ratio=adaptive и duration=-1; всегда опрашивайте путь статуса generations и сохраняйте идентификатор задачи.
7. Контрольный список действий
- Создайте ключ на портале разработчика ToAPIs.
- Подтвердите, что
wan3.0-video(иwan3.0-video-prime, если он нужен) виден для вашего ключа черезGET /v1/models?type=video— не отправляйтеwan-3-prime. - Прогоните фрагмент cURL с
duration: 5,ratio: "16:9"иresolution: "1080p". - Опрашивайте
GET /v1/videos/generations/{id}с ограниченным дедлайном и скачивайте результат доexpires_at. - Далее: Wan 3.0 Prime против Wan 2.6 Flash для документированного сравнения возможностей и стоимости и model guide wan3.0-video для живого статуса каталога.







