Skip to main content

Обзор

Wan (Tongyi Wanxiang) — это серия моделей генерации видео от Alibaba Cloud. APIYI напрямую подключается к Alibaba Cloud Model Studio через сквозной канал DashScope, поэтому один ключ APIYI (начинающийся с sk-) открывает доступ ко всем возможностям видео Wan без отдельного аккаунта Alibaba Cloud. Текущий флагман — Wan2.7, охватывающий четыре основных сценария использования:
🎬 Ключевая особенность: все четыре возможности используют один и тот же асинхронный эндпоинт и одну и ту же структуру запроса. Переключайте сценарии использования, изменяя только поле model. Нативная поддержка разрешений 720P / 1080P и целочисленной длительности от 2 до 15 секунд; wan2.7-i2v также поддерживает управляющее аудио для синхронизации губ. Идеально подходит для производства коротких видео, материалов для e-commerce, озвучивания цифровых аватаров и креативного маркетинга.

API текст-в-видео

wan2.7-t2v генерирует видео из чистого text prompt — самый простой способ начать.

API изображения-в-видео

wan2.7-i2v использует первый кадр + необязательное управляющее аудио для синхронизации губ / рэпа.

API референса-в-видео

wan2.7-r2v сохраняет характеристики объекта из reference images/videos, с голосовым референсом.

API редактирования видео

wan2.7-videoedit редактирует видео с помощью референсных изображений: замена одежды, замена фона и т. д.

Визуальное тестирование API

Отлаживайте этот эндпоинт напрямую в визуальном инструменте тестирования iCover — код не требуется.

Поиск / загрузка асинхронных задач

Просматривайте отправленные задачи на видео и скачивайте ссылки на видео в консоли APIYI — запись для поиска вне API.

Почему использовать Wan в APIYI

Один ключ APIYI для всех возможностей

Не требуется регистрация в Alibaba Cloud, настройка региона или переменных окружения. Один ключ APIYI вызывает все четыре возможности Wan2.7, а также серию HappyHorse.

Прямой доступ, без VPN

Подключайтесь напрямую к api.apiyi.com, доступно как из дата-центров материкового Китая, так и из домашних сетей, без необходимости настраивать региональный endpoint Alibaba Cloud.

Нет списания при сбое

Задачи, завершающиеся failed (недоступный media URL, чувствительный prompt, нехватка upstream-мощностей и т. д.), не тарифицируются, так что повторяйте попытки свободно.

Сквозная передача протокола DashScope

Тело запроса сопоставляется один к одному с нативным протоколом DashScope Alibaba Cloud, поэтому вы можете мигрировать, следуя официальной документации; ответы нормализуются для удобного периодического опроса.

Основные возможности

Асинхронный эндпоинт 4-в-1

t2v / i2v / r2v / video-edit используют общий POST /wan/api/v1/...video-synthesis. Отправьте задачу, получите task_id, опрашивайте и скачивайте. Простое управление пакетными задачами.

Синхронизация губ по аудио

wan2.7-i2v поддерживает driving_audio, благодаря чему статичный портрет повторяет движения рта и ритм аудио. Отлично подходит для рэпа / озвучки / цифровых людей.

Референс нескольких объектов

wan2.7-r2v объединяет референсные изображения + референсные видео (максимум 5 в сумме), которые указываются в prompt как «image 1 / video 1», с поддержкой голосового референса.

Несколько разрешений и длительностей

Разрешения 720P / 1080P, длительность 2-15 секунд целыми числами. prompt_extend умное переписывание дополнительно повышает качество для коротких prompt.

Поддерживаемые модели

wan2.7-videoedit предназначен для редактирования видео с помощью изображений. Отдельный wan2.7-image-pro — это модель для изображений (использует /v1/images/generations) и выходит за рамки этого video endpoint, так что не путайте их. Для устаревшей серии Wan2.6 см. Исторические версии.

⚠️ Выбор эндпоинта (самое важное)

APIYI монтирует два пути, но только endpoint с проксированием DashScope полностью поддерживает все возможности Wan:
Если в какой-либо документации или примере вам предлагают отправлять задачи видео Wan через /v1/videos, игнорируйте это. Адаптация этого пути для полей i2v / r2v media неполная и вызывает upstream-ошибку [InvalidParameter] Field required: input.media. Все запросы на создание видео Wan отправляются в /wan/api/v1/...video-synthesis.

Поток асинхронных вызовов

Весь процесс состоит из трёх асинхронных шагов: создание задачи → опрос статуса → скачивание видео.
1

Создайте задачу

POST /wan/api/v1/services/aigc/video-generation/video-synthesis с заголовком X-DashScope-Async: enable. Он сразу возвращает task_id.
2

Опросите статус

GET /v1/tasks/{task_id}Authorization) каждые 5-10 секунд (не реже чем раз в 3 секунды), пока status не станет completed.
3

Скачайте видео

Получите mp4 напрямую из result_url ответа. Не отправляйте заголовок Authorization (это подписанная OSS прямая ссылка; добавление Auth приводит к 403).

Справка по статусам задачи

Верхнеуровневое поле status ответа GET /v1/tasks/{task_id} (уже нормализовано APIYI):

Полный Python-клиент

Объяснение ключевых параметров

При отправке тело запроса использует вложенную структуру DashScope: { model, input: { prompt, media[] }, parameters: {...} }.

Поля input

Типы media[]

Каждому медиа-объекту нужны как минимум type + url. url должен быть общедоступной ссылкой https, которую можно напрямую получить через GET (сначала загрузите локальные файлы в OSS / CDN).

Поля parameters

duration должен быть целым числом 5, а не строкой "5", иначе вы получите cannot unmarshal string into Go struct field ... of type int. Запись resolution в верхнем регистре (720P) надежнее.

Выбор между Wan и HappyHorse

Wan и HappyHorse — это обе видеомодели Alibaba, и они используют один и тот же эндпоинт и схему (переключайтесь между ними, меняя только имя model), но их сильные стороны различаются:
Нужны lip-sync / rap / озвучка digital-human → выберите wan2.7-i2v (единственный вариант с audio drive). Нужно много reference images, чтобы сохранить согласованность объекта → рассмотрите HappyHorse r2v (до 9 изображений).

Лучшие практики

1

Сначала тестируйте на 720P / 5 секунд

В процессе разработки быстро проверяйте prompt и направление камеры на коротких клипах низкого разрешения, а после завершения переходите к 720P / 1080P и более длительным роликам, чтобы сократить затраты и время ожидания.
2

Всегда включайте prompt_extend

prompt_extend: true заметно улучшает качество для коротких prompt, ценой лишь нескольких дополнительных секунд генерации.
3

Опрос каждые 5-10 секунд

Никогда не делайте интервал меньше 3 секунд (иначе вы упретесь в лимит запросов) и не блокируйте выполнение на длительных задачах бесконечно. 720P / 5 секунд обычно занимает 70-140 секунд; 1080P / более длинные клипы могут превышать 5 минут.
4

Установите клиентский timeout на 20 минут как запасной предел

1080P или клипы длиннее 10 секунд заметно медленнее; задайте для цикла опроса запасной timeout на 20 минут.
5

Скачивайте сразу после получения result_url

result_url по умолчанию истекает через 24 часа и представляет собой подписанную прямую ссылку OSS, поэтому при скачивании не отправляйте заголовок Authorization. В production всегда пересохраняйте его в своем OSS / CDN.
6

Делайте отправки идемпотентными

Неудачные задачи не тарифицируются, но повторная отправка той же задачи тарифицируется снова. Поддерживайте сопоставление «ID бизнеса → task_id» на уровне приложения, чтобы избежать случайных списаний.

Коды ошибок и повторные попытки

Ошибки возникают на двух этапах и обрабатываются по-разному:
Рекомендуемое поведение клиента: повтор с экспоненциальным backoff при HTTP 5xx / network errors (1s / 4s / 16s); сразу показывайте HTTP 4xx без повтора; задачу failed с [InvalidImageUrl] можно повторить (возможно, временная проблема сети), а [InvalidParameter] / чувствительные слова не следует повторять.

FAQ

/v1/videos — это эндпоинт OpenAI плоского формата с неполной поддержкой i2v / r2v для Wan: поля media, например media, отбрасываются, а upstream Alibaba Cloud возвращает [InvalidParameter] Field required: input.media. Все запросы на создание видео Wan отправляются в /wan/api/v1/services/aigc/video-generation/video-synthesis, а запросы на получение всегда идут в /v1/tasks/{task_id}.
Он сообщает endpoint, что «это асинхронная задача, сразу верните task_id и не блокируйте выполнение». Он обязателен для каждого запроса на создание; если его опустить, возвращается current user api does not support synchronous calls. Запрос на получение (GET) этот заголовок не требует.
APIYI нормализует все запросы на опрос видео-задач к /v1/tasks/{task_id}. Независимо от того, какой путь вы использовали для создания задачи, вы опрашиваете ее через этот единственный endpoint, а поля верхнего уровня ответа status / progress / result_url / error остаются согласованными.
Уберите заголовок Authorization. result_url уже является предварительно подписанной прямой ссылкой Alibaba Cloud OSS; если добавить APIYI Key, OSS отклонит ее:
По умолчанию ссылка действительна 24 часа. После истечения срока снова выполните GET /v1/tasks/{task_id}, и обычно вы получите свежую result_url, но срок действия опроса по самому task_id тоже составляет 24 часа (после этого возвращается UNKNOWN). Для долгосрочного хранения как можно скорее загрузите файл в свое хранилище.
Нет. Прогресс, который сообщает upstream Alibaba Cloud, имеет грубую градацию (только уровни 0% / 10% / 30% / 100%). Пока status все еще in_progress, продолжайте ждать; обычно он сразу прыгает с 30% до 100%.
На практике вы можете отправить 4-8 задач одновременно без упора в лимит запросов. В production держите одновременно активные задачи ≤10; все, что выше, уходит в очередь. У query API довольно высокий RPS по умолчанию, но интервал опроса в 5-10 секунд все равно рекомендуется.
status=failed не тарифицируется. Но учтите: повторная отправка той же задачи тарифицируется снова, поэтому сделайте ее идемпотентной. Во время тестирования можно отключить prompt_extend и использовать 720P / 5 seconds / short prompts, чтобы снизить стоимость за единицу.
Да. Серия Wan2.6 (включая wan2.6-r2v-flash) по-прежнему есть в списке доступных вызовов, с тем же протоколом, что и Wan2.7; достаточно изменить имя model. См. Исторические версии.

Настройка группы

Серии Wan и HappyHorse используют одну группу Wan&HappyHorse — один Token может вызывать обе серии. Видео-модели тарифицируются за секунду, поэтому Token должен соответствовать двум условиям, чтобы маршрутизация прошла успешно:
  1. Модель тарификации: выберите Pay-as-you-go Priority или Pay-as-you-go — видео тарифицируется за секунду, поэтому Token с Pay-per-request не может маршрутизироваться
  2. Группа: выберите группу, которая включает Wan&HappyHorse
Create Token dialog: billing model set to Pay-as-you-go Priority, group dropdown showing Wan&HappyHorse (rate 0.14x), one Token usable for both Wan2.7 and HappyHorse

Create Token: set billing model to Pay-as-you-go Priority and group to Wan&HappyHorse (0.14x) to call every Wan2.7 and HappyHorse video model (the screenshot shows the group's former name Wan, since renamed to Wan&HappyHorse)

Тарификация

Цена по умолчанию = 98% от официальной цены Alibaba (легко вычислить)

В консоли группа Wan&HappyHorse показывает коэффициент 0.14x, который выражается во встроенной единице тарификации RMB. Поскольку APIYI ведет тарификацию в USD по фиксированному курсу 1:7, фактический пересчет такой:
Иными словами, цена по умолчанию = 98% от официальной цены Alibaba — дешевле, чем покупать напрямую у Alibaba, и без необходимости самостоятельно выстраивать зарубежный канал.
Пересчет: цена в USD за секунду = официальная цена в RMB × 0.14 (то есть × 0.98 ÷ 7). Например, официальная цена 1080P в ¥1.0/s → $0.14/s, то есть ровно 0.14x, который отображается в консоли.

Подробности цены (цена по умолчанию, тарификация по секундам)

Wan2.7 text-to-video / image-to-video / reference-to-video тарифицируются одинаково, с двумя уровнями — 720P / 1080P (480P не поддерживается):
  • wan2.7-r2v по умолчанию равен 1080P, а длительность ограничена 10 секундами, если в reference media есть видео.
  • wan2.7-videoedit (редактирование видео) формирует выходную длительность по исходному видео и тарифицируется по фактическим секундам результата, а не по duration.
  • Указанные цены — это цена по умолчанию (98% от официальной); с максимальным бонусом за пополнение эффективная цена примерно равна значению из таблицы ÷ 1.2 (например, 1080P 5 s $0.70 → примерно $0.58).

Ступенчатые бонусы за пополнение для еще более низкой эффективной цены

После подключения к программе бонусов за пополнение зачисленный баланс можно увеличить примерно до ~1.2x, еще сильнее снижая эффективную цену:
Таким образом, крупные клиенты могут снизить цену вплоть до ~81.6% от официальной цены.
  • Единица тарификации = уровень разрешения × длительность (секунды); неудачные задачи не тарифицируются.
  • 1:7 — это фиксированный расчетный курс обмена (не льготный); он единообразно применяется ко всем пополнениям в USD.
  • Для самых высоких уровней бонусов и подходящих каналов см. бонусы за пополнение. Актуальный курс является приоритетным в консоли.

Связанные документы

Песочница Text-to-Video

wan2.7-t2v отладка в реальном времени + примеры кода

Песочница Image-to-Video

wan2.7-i2v первый кадр + управляющее аудио

Песочница Reference-to-Video

wan2.7-r2v многообъектный референс + голос

Песочница Video Edit

wan2.7-videoedit замена одежды / фона

Исторические версии (Wan2.6)

серия Wan2.6 и заметки по миграции

Серия HappyHorse

Также на базе Alibaba, руководство по сравнению и выбору
Официальная документация Alibaba Cloud (справка): help.aliyun.com/zh/model-studio/text-to-video-api-reference. По вопросам или предложениям, пожалуйста, откройте обращение в консоли APIYI.