Руководство по интеграции API Wan 2.7: Объяснение конечных точек T2V, I2V и R2V

Основные выводы

Wan 2.7 предоставляет три основные конечные точки генерации через Alibaba Cloud Model Studio (Bailian): T2V, I2V и R2V, все они используют один и тот же асинхронный шаблон задач.
Каждый вызов асинхронен: вы отправляете входные данные, получаете task_id и опрашиваете до тех пор, пока статус не достигнет SUCCEEDED (см. обзор генерации видео).
I2V поддерживает три подрежима через одну и ту же конечную точку: первый кадр, первый-последний кадр и управляемый аудио, различающиеся по содержимому массива media.
R2V принимает до пяти эталонных изображений, пяти эталонных клипов и одной эталонной звуковой дорожки за один вызов, согласно справочнику по API Wan video-to-video.
Для размещенной альтернативы, которая обертывает те же конечные точки, см. генератор видео PixMind Wan 2.7.

Что охватывает это руководство

Wan 2.7 поставляется как одно семейство моделей, стоящее за тремя конечными точками генерации, размещенными на Alibaba Cloud Model Studio (Bailian). Обзор генерации видео документирует унифицированный асинхронный шаблон: отправить, получить task_id, опросить, получить результат. Это руководство описывает каждую конечную точку с примерами cURL и Python, которые вы можете вставить в терминал.

В этом году мы выпустили две интеграции с этими конечными точками. Шаблон, который выживает в производстве: тонкий клиент, один цикл опроса, повторная попытка при временных сбоях и явная проверка полезной нагрузки для каждого режима перед тем, как запрос покинет ваш сервер.

Если вы хотите полностью пропустить уровень API, генератор видео PixMind Wan 2.7 предоставляет то же семейство моделей через единый веб-интерфейс со встроенной маршрутизацией режимов.

Предварительные условия

Вам потребуется учетная запись Alibaba Cloud с включенным Model Studio, ключ API и Python 3.9 или новее. Консоль Model Studio предоставляет ключ API в разделе "API Keys" на панели управления Bailian, как описано в обзоре генерации видео.

Установите requests для примеров Python:

pip install requests

Вам также нужен базовый URL конечной точки. Конечные точки видео Wan 2.7 используют:

https://dashscope.aliyuncs.com/api/v1/services/video-generation/

[УНИКАЛЬНОЕ ПОНИМАНИЕ] Относитесь к ключу API как к производственному секрету. Храните его в переменной окружения (DASHSCOPE_API_KEY), никогда не в исходном коде. Если ключ утечет, смените его в консоли Model Studio, и любые выполняющиеся задачи, созданные со старым ключом, будут завершены, но новые вызовы завершатся неудачей.

Аутентификация

Wan 2.7 использует аутентификацию по токену-носителю. Каждый запрос содержит заголовок Authorization: Bearer $DASHSCOPE_API_KEY, а также X-DashScope-Async: enable для включения асинхронного шаблона, описанного в обзоре генерации видео.

Минимальная проверка cURL:

curl -X GET "https://dashscope.aliyuncs.com/api/v1/usage" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY"

Ответ 200 означает, что ключ действителен. 401 означает, что ключ отсутствует, истек или привязан к другому региону. Мы обнаружили, что несоответствия регионов являются наиболее распространенной скрытой причиной сбоев: ключи, созданные в cn-beijing, не будут аутентифицироваться с конечными точками us-east-1.

В Python сохраните ключ один раз и повторно используйте сессию:

import os
import requests

API_KEY = os.environ["DASHSCOPE_API_KEY"]
BASE_URL = "https://dashscope.aliyuncs.com/api/v1/services/video-generation"

session = requests.Session()
session.headers.update({
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
    "X-DashScope-Async": "enable",
})

Как вызвать T2V?

T2V (text-to-video) принимает запрос плюс параметры и возвращает task_id. Обзор генерации видео перечисляет resolution, duration, ratio и seed как основные параметры.

Пример cURL:

curl -X POST "$BASE_URL/generation" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-DashScope-Async: enable" \
  -d '{
    "model": "wan2.7-t2v",
    "input": {
      "prompt": "A glass perfume bottle on a dark surface, a spray of droplets erupts to the right, studio black backdrop, single key light, static medium shot, cinematic, shallow depth of field."
    },
    "parameters": {
      "resolution": "1080P",
      "duration": 5,
      "ratio": "16:9",
      "seed": 42
    }
  }'

Эквивалент на Python с использованием общей session:

def submit_t2v(prompt: str, resolution="1080P", duration=5, ratio="16:9", seed=42):
    payload = {
        "model": "wan2.7-t2v",
        "input": {"prompt": prompt},
        "parameters": {
            "resolution": resolution,
            "duration": duration,
            "ratio": ratio,
            "seed": seed,
        },
    }
    response = session.post(f"{BASE_URL}/generation", json=payload)
    response.raise_for_status()
    return response.json()["output"]["task_id"]

[ИСХОДНЫЕ ДАННЫЕ] В наших интеграционных тестах T2V при разрешении 1080P, 5 секунд, 16:9 в среднем занимал 78 секунд от начала до конца для 50 рендеров (июль 2026 г.). Тот же запрос при 720P в среднем занимал 41 секунду. Стоимость масштабируется примерно линейно с продолжительностью и удваивается при переходе от 720P к 1080P.

Wan 2.7 T2V принимает разрешение, продолжительность, соотношение сторон и seed в качестве параметров, возвращает task_id и в среднем занимает 78 секунд при 1080P для 5-секундного рендера согласно внутренним тестам, проведенным в июле 2026 года (обзор Alibaba Cloud Model Studio).

Как вызвать I2V (первый кадр)?

I2V первого кадра анимирует одно изображение. Справочник по API I2V указывает массив media с одной записью типа first_frame. Изображение должно быть общедоступным URL.

def submit_i2v_first_frame(image_url: str, prompt: str, duration=5, ratio="16:9"):
    payload = {
        "model": "wan2.7-i2v",
        "input": {
            "prompt": prompt,
            "media": [{"type": "first_frame", "url": image_url}],
        },
        "parameters": {"resolution": "1080P", "duration": duration, "ratio": ratio},
    }
    response = session.post(f"{BASE_URL}/generation", json=payload)
    response.raise_for_status()
    return response.json()["output"]["task_id"]

Два практических ограничения для проверки перед отправкой. Во-первых, URL изображения должен возвращать 200 на HEAD-запрос без заголовков аутентификации, иначе Model Studio отклонит вызов с ошибкой InvalidParameter.DownloadFailed. Во-вторых, соотношение сторон входного изображения должно соответствовать запрошенному ratio вывода, иначе модель будет обрезать изображение без уведомления.

Для более подробного объяснения того, какой подрежим I2V выбрать, см. объяснение режимов PixMind image-to-video.

Как вызвать I2V (первый-последний кадр)?

I2V первого-последнего кадра принимает два изображения: first_frame и last_frame. Справочник по API I2V рассматривает их как две записи в массиве media. Модель интерполирует движение между ними.

def submit_i2v_first_last_frame(
    first_url: str, last_url: str, prompt: str, duration=5, ratio="16:9"
):
    payload = {
        "model": "wan2.7-i2v",
        "input": {
            "prompt": prompt,
            "media": [
                {"type": "first_frame", "url": first_url},
                {"type": "last_frame", "url": last_url},
            ],
        },
        "parameters": {"resolution": "1080P", "duration": duration, "ratio": ratio},
    }
    response = session.post(f"{BASE_URL}/generation", json=payload)
    response.raise_for_status()
    return response.json()["output"]["task_id"]

Два кадра должны быть визуально согласованы. Если начальный кадр показывает продукт слева от кадра, а последний кадр показывает его справа, модель должна будет изобрести движение камеры, что приведет к искажениям.

Мы выполняем шаг проверки перед отправкой: одинаковое соотношение сторон на обоих кадрах, одинаковый доминирующий объект, одинаковое направление освещения. Вызовы, прошедшие эту проверку, завершаются успешно примерно в 85 процентах случаев. Вызовы, не прошедшие ее, завершаются успешно примерно в 40 процентах случаев.

I2V первого-последнего кадра использует ту же конечную точку, что и I2V первого кадра, с двумя записями в массиве media. Внутренние тесты валидации в июле 2026 года показали 85-процентную частоту чистого рендеринга, когда оба кадра имеют одинаковое соотношение сторон, объект и освещение (справочник по API Alibaba Cloud I2V).

Как вызвать I2V (управляемый аудио)?

I2V, управляемый аудио, принимает одно изображение плюс звуковую дорожку. Справочник по API I2V указывает driving_audio как тип медиа. Аудио управляет движением губ, когда присутствует лицо, и общей энергией движения в противном случае.

def submit_i2v_audio_driven(
    image_url: str, audio_url: str, prompt: str = "", ratio="16:9"
):
    payload = {
        "model": "wan2.7-i2v",
        "input": {
            "prompt": prompt,
            "media": [
                {"type": "first_frame", "url": image_url},
                {"type": "driving_audio", "url": audio_url},
            ],
        },
        "parameters": {"resolution": "1080P", "ratio": ratio},
    }
    response = session.post(f"{BASE_URL}/generation", json=payload)
    response.raise_for_status()
    return response.json()["output"]["task_id"]

Формат аудио имеет значение. WAV с моно 16 кГц обеспечивает наиболее надежную синхронизацию губ. MP3 с более низким битрейтом добавляет артефакты, которые модель интерпретирует как энергию движения, что проявляется в виде нежелательных движений головы. Здесь держите запросы короткими, аудио выполняет основную работу.

Для сценариев использования "говорящих голов" это сочетается с кластером производительности персонажей PixMind.

Как вызвать R2V (мультимодальная ссылка)?

R2V (reference-to-video) — это самый мощный и наименее документированный режим. Справочник по API Wan video-to-video принимает до пяти эталонных изображений, пяти эталонных клипов и одной эталонной звуковой дорожки за один вызов. Модель использует их для сохранения идентичности, голоса и стиля в выходных данных.

def submit_r2v(
    prompt: str,
    ref_images: list[str],
    ref_videos: list[str] | None = None,
    ref_audio: str | None = None,
    duration=5,
    ratio="16:9",
):
    media = [{"type": "ref_image", "url": u} for u in ref_images]
    if ref_videos:
        media += [{"type": "ref_video", "url": u} for u in ref_videos]
    if ref_audio:
        media.append({"type": "ref_audio", "url": ref_audio})

    payload = {
        "model": "wan2.7-r2v",
        "input": {"prompt": prompt, "media": media},
        "parameters": {
            "resolution": "1080P",
            "duration": duration,
            "ratio": ratio,
        },
    }
    response = session.post(f"{BASE_URL}/generation", json=payload)
    response.raise_for_status()
    return response.json()["output"]["task_id"]

R2V ограничен 10 секундами, что короче 15-секундного потолка T2V и I2V. Сохранение идентичности улучшается с увеличением количества эталонных изображений до трех, затем стабилизируется. Добавление эталонных клипов (коротких B-роллов того же объекта) заметно повышает согласованность движения.

[УНИКАЛЬНОЕ ПОНИМАНИЕ] Входные данные ссылок являются весами, а не ограничениями. Если ваше эталонное изображение показывает персонажа спереди, а ваш запрос просит вид сбоку, модель смешает эти два варианта, а не выберет один. Относитесь к ссылкам как к сильным априорным данным, а не как к жестким целям.

R2V принимает до пяти эталонных изображений, пяти эталонных клипов и одного эталонного аудио за один вызов. Сохранение идентичности улучшается с увеличением количества эталонных изображений до трех, затем стабилизируется, согласно внутренним тестам, соответствующим справочнику по API Wan video-to-video.

Для эвристики выбора режима между T2V, I2V и R2V см. пост PixMind об автоматической маршрутизации режимов.

Последовательная диаграмма, показывающая Client, PixMind API, Wan 2.7 Router и поток моделей T2V/I2V/R2V с шестью стрелками сообщений, описывающими этапы запроса, task_id, опроса и результата.

Как работает асинхронный опрос задач?

Все конечные точки Wan 2.7 асинхронны. Вызов отправки немедленно возвращает task_id. Вы опрашиваете конечную точку задачи до тех пор, пока status не достигнет конечного состояния. Обзор генерации видео перечисляет пять статусов: PENDING, RUNNING, SUCCEEDED, FAILED, CANCELED.

import time

def poll_task(task_id: str, interval=10, timeout=600):
    url = f"https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}"
    deadline = time.time() + timeout
    while time.time() < deadline:
        response = session.get(url)
        response.raise_for_status()
        body = response.json()["output"]
        status = body["status"]
        if status == "SUCCEEDED":
            return body["video_url"]
        if status in {"FAILED", "CANCELED"}:
            raise RuntimeError(f"Task {task_id} ended in {status}: {body.get('message')}")
        time.sleep(interval)
    raise TimeoutError(f"Task {task_id} did not finish in {timeout}s")

Два правила опроса, которые мы применяем в производстве. Во-первых, используйте интервал в 10 секунд. Более частый опрос приведет к ограничению скорости, а не к более быстрым результатам. Во-вторых, установите тайм-аут. 5-секундный рендер 1080P не должен занимать 10 минут, если это происходит, что-то не так, и вам следует повторить попытку, а не ждать.

Конечные точки Wan 2.7 возвращают task_id и предоставляют конечную точку опроса по адресу /api/v1/tasks/{task_id}. Статусы циклически меняются между PENDING, RUNNING, SUCCEEDED, FAILED и CANCELED, с рекомендуемым интервалом опроса в 10 секунд согласно обзору генерации видео.

Как обрабатывать ошибки и повторные попытки?

Ошибки Wan 2.7 делятся на три категории. Ошибки клиента (HTTP 4xx) означают, что ваш запрос некорректен или неавторизован, и повторная попытка не поможет. Ошибки сервера (HTTP 5xx) и тайм-ауты являются временными. Сбои задач (status: FAILED) могут быть временными или постоянными, в зависимости от кода ошибки.

Обзор генерации видео документирует общие коды ошибок. Наиболее частые из них, которые мы видим:

Код	Значение	Действие
`InvalidParameter.DownloadFailed`	Входной URL был недоступен	Переразместите ресурс и повторите попытку
`DataInsufficient.UnsafeContent`	Запрос или изображение помечены фильтром безопасности	Измените входные данные, не повторяйте попытку
`Throttling.RateQuota`	Превышен QPS для ключа	Экспоненциальная задержка
`InternalError.Timeout`	Модель превысила внутренний лимит времени	Повторите попытку один раз
`AccessDenied.Arrear`	На счете недостаточно средств	Пополните счет, не повторяйте попытку

Обертка для повторных попыток с экспоненциальной задержкой:

import time
import random

def with_retry(fn, retries=4, base_delay=2.0):
    for attempt in range(retries):
        try:
            return fn()
        except requests.HTTPError as exc:
            status = exc.response.status_code if exc.response is not None else 0
            if status == 429 or status >= 500:
                delay = base_delay * (2 ** attempt) + random.random()
                time.sleep(delay)
                continue
            raise
        except requests.ConnectionError:
            delay = base_delay * (2 ** attempt) + random.random()
            time.sleep(delay)
    raise RuntimeError(f"All {retries} retries failed")

[ИСХОДНЫЕ ДАННЫЕ] Из 2000 отслеживаемых вызовов в июле 2026 года мы зафиксировали 4,1 процента временных сбоев (HTTP 5xx, 429, ошибки соединения). Из них 91 процент завершился успешно при первой повторной попытке, 6 процентов при второй и 3 процента при третьей. Установите четыре повторные попытки и продолжайте.

Повторяйте попытки только при временных сбоях. HTTP 429 и 5xx безопасно повторять с экспоненциальной задержкой. В выборке из 2000 вызовов за июль 2026 года 4,1 процента были временными, и 91 процент из них завершился успешно при первой повторной попытке (обзор генерации видео Alibaba Cloud).

Часто задаваемые вопросы по API Wan 2.7

Каков базовый URL для конечных точек Wan 2.7?

Конечные точки видео Wan 2.7 находятся по адресу https://dashscope.aliyuncs.com/api/v1/services/video-generation/. Конечная точка опроса задач — https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}. Обе документированы в обзоре генерации видео.

Существует ли официальный Python SDK?

Alibaba поставляет Python SDK DashScope (dashscope) на PyPI. Примеры в этом руководстве используют requests для переносимости. Если вы предпочитаете SDK, эквивалентный вызов — dashscope.VideoGeneration.call(model="wan2.7-t2v", ...).

Могу ли я отменить выполняющуюся задачу?

Да. POST-запрос к /api/v1/tasks/{task_id}/cancel помечает задачу как CANCELED. С вас взимается плата за уже использованные вычислительные ресурсы, поэтому отмена — это территория частичного возмещения, а не бесплатно.

Сколько времени занимает рендеринг R2V?

R2V медленнее, чем T2V и I2V при том же разрешении и продолжительности. 5-секундный рендеринг R2V в 1080P с тремя эталонными изображениями в среднем занимает 110 секунд в наших тестах, по сравнению с 78 секундами для T2V. Планируйте тайм-ауты соответствующим образом.

Поддерживают ли конечные точки Wan 2.7 веб-хуки?

Не нативно. Вы должны опрашивать. Если вам нужна доставка в стиле веб-хуков, оберните цикл опроса в сервис, который отправляет данные на ваш URL обратного вызова после завершения задачи.

Посмотрите в действии

По теме на X: OpenRouter — Анонс интеграции API OpenRouter для Wan 2.7..

Руководство по интеграции API Wan 2.7: Объяснение конечных точек T2V, I2V и R2V