Przewodnik integracji API Wan 2.7: Wyjaśnienie punktów końcowych T2V, I2V i R2V
Kluczowe wnioski
- Wan 2.7 udostępnia trzy podstawowe punkty końcowe generowania poprzez Alibaba Cloud Model Studio (Bailian): T2V, I2V i R2V, wszystkie korzystające z tego samego asynchronicznego wzorca zadań.
- Każde wywołanie jest asynchroniczne: przesyłasz dane wejściowe, otrzymujesz
task_idi odpytujesz, aż status osiągnieSUCCEEDED(zobacz przegląd generowania wideo). - I2V akceptuje trzy podtryby poprzez ten sam punkt końcowy: pierwsza klatka, pierwsza-ostatnia klatka i sterowane dźwiękiem, rozróżniane przez zawartość tablicy
media. - R2V przyjmuje do pięciu obrazów referencyjnych, pięciu klipów referencyjnych i jednej ścieżki audio referencyjnej w jednym wywołaniu, zgodnie z dokumentacją API Wan video-to-video.
- Aby zapoznać się z hostowaną alternatywą, która opakowuje te same punkty końcowe, zobacz generator wideo PixMind Wan 2.7.
Co obejmuje ten przewodnik
Wan 2.7 jest dostarczany jako jedna rodzina modeli za trzema punktami końcowymi generowania hostowanymi w Alibaba Cloud Model Studio (Bailian). Przegląd generowania wideo dokumentuje ujednolicony wzorzec asynchroniczny: prześlij, uzyskaj task_id, odpytaj, pobierz wynik. Ten przewodnik omawia każdy punkt końcowy z przykładami cURL i Python, które można wkleić do terminala.
W tym roku dostarczyliśmy dwie integracje z tymi punktami końcowymi. Wzorzec, który sprawdza się w produkcji, to: cienki klient, pojedyncza pętla odpytywania, ponawianie w przypadku przejściowych błędów i jawna walidacja ładunku dla każdego trybu przed opuszczeniem serwera przez żądanie.
Jeśli chcesz całkowicie pominąć warstwę API, generator wideo PixMind Wan 2.7 udostępnia tę samą rodzinę modeli poprzez pojedynczy interfejs internetowy z wbudowanym routingiem trybów.
Wymagania wstępne
Potrzebujesz konta Alibaba Cloud z włączonym Model Studio, klucza API i Pythona 3.9 lub nowszego. Konsola Model Studio udostępnia klucz API w sekcji "API Keys" na pulpicie nawigacyjnym Bailian, zgodnie z dokumentacją w przeglądzie generowania wideo.
Zainstaluj requests dla przykładów w Pythonie:
pip install requests
Potrzebujesz również bazowego adresu URL punktu końcowego. Punkty końcowe wideo Wan 2.7 używają:
https://dashscope.aliyuncs.com/api/v1/services/video-generation/
[UNIKALNA WSKAZÓWKA] Traktuj klucz API jak tajemnicę produkcyjną. Przechowuj go w zmiennej środowiskowej (DASHSCOPE_API_KEY), nigdy w kodzie źródłowym. Jeśli klucz wycieknie, obróć go z konsoli Model Studio, a wszelkie zadania w toku utworzone za pomocą starego klucza zostaną ukończone, ale nowe wywołania zakończą się niepowodzeniem.
Uwierzytelnianie
Wan 2.7 używa uwierzytelniania tokenem okaziciela. Każde żądanie zawiera nagłówek Authorization: Bearer $DASHSCOPE_API_KEY oraz X-DashScope-Async: enable, aby włączyć wzorzec asynchroniczny udokumentowany w przeglądzie generowania wideo.
Minimalne sprawdzenie cURL:
curl -X GET "https://dashscope.aliyuncs.com/api/v1/usage" \
-H "Authorization: Bearer $DASHSCOPE_API_KEY"
Odpowiedź 200 oznacza, że klucz jest prawidłowy. 401 oznacza, że klucz brakuje, wygasł lub jest przypisany do innego regionu. Stwierdziliśmy, że niezgodności regionów są najczęstszą cichą awarią: klucze utworzone w cn-beijing nie uwierzytelnią się w punktach końcowych us-east-1.
W Pythonie przechowuj klucz raz i używaj ponownie sesji:
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",
})
Jak wywołać T2V?
T2V (text-to-video) przyjmuje prompt plus parametry i zwraca task_id. Przegląd generowania wideo wymienia resolution, duration, ratio i seed jako główne parametry.
Przykład 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
}
}'
Odpowiednik w Pythonie używający współdzielonej 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"]
[ORYGINALNE DANE] W naszych testach integracyjnych, T2V w rozdzielczości 1080P, 5 sekund, 16:9, uśredniało 78 sekund od początku do końca w 50 renderach (lipiec 2026). Ten sam prompt w 720P uśredniał 41 sekund. Koszt skaluje się mniej więcej liniowo z czasem trwania i podwaja się z 720P do 1080P.
Wan 2.7 T2V akceptuje rozdzielczość, czas trwania, proporcje i seed jako parametry, zwraca task_id i uśrednia 78 sekund w 1080P dla 5-sekundowego renderu, zgodnie z wewnętrznymi testami przeprowadzonymi w lipcu 2026 (przegląd Alibaba Cloud Model Studio).
Jak wywołać I2V (pierwsza klatka)?
I2V z pierwszą klatką animuje pojedynczy obraz. Dokumentacja API I2V określa tablicę media z jednym wpisem typu first_frame. Obraz musi być publicznym adresem 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"]
Dwa praktyczne ograniczenia do walidacji przed przesłaniem. Po pierwsze, adres URL obrazu musi zwrócić 200 na żądanie HEAD bez nagłówków uwierzytelniających, w przeciwnym razie Model Studio odrzuci wywołanie z błędem InvalidParameter.DownloadFailed. Po drugie, proporcje obrazu wejściowego powinny odpowiadać żądanym proporcjom ratio, w przeciwnym razie model przytnie obraz bez powiadomienia.
Aby uzyskać szczegółowy opis, który podtryb I2V wybrać, zobacz wyjaśnienie trybów PixMind image-to-video.
Jak wywołać I2V (pierwsza-ostatnia klatka)?
I2V z pierwszą i ostatnią klatką przyjmuje dwa obrazy: first_frame i last_frame. Dokumentacja API I2V traktuje je jako dwa wpisy w tablicy media. Model interpoluje ruch między nimi.
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"]
Dwie klatki powinny być wizualnie spójne. Jeśli klatka początkowa pokazuje produkt po lewej stronie kadru, a ostatnia klatka pokazuje go po prawej, model musi wymyślić ruch kamery, co prowadzi do zniekształceń.
Przed przesłaniem przeprowadzamy krok walidacji: te same proporcje obrazu w obu klatkach, ten sam dominujący obiekt, ten sam kierunek oświetlenia. Wywołania, które przechodzą tę kontrolę, kończą się pomyślnie w około 85 procentach przypadków. Wywołania, które jej nie przechodzą, kończą się pomyślnie w około 40 procentach przypadków.
I2V z pierwszą i ostatnią klatką używa tego samego punktu końcowego co I2V z pierwszą klatką, z dwoma wpisami w tablicy media. Wewnętrzne testy walidacyjne z lipca 2026 wykazały 85-procentowy wskaźnik czystego renderowania, gdy obie klatki mają te same proporcje, temat i oświetlenie (dokumentacja API Alibaba Cloud I2V).
Jak wywołać I2V (sterowane dźwiękiem)?
I2V sterowane dźwiękiem przyjmuje pojedynczy obraz plus ścieżkę audio. Dokumentacja API I2V wymienia driving_audio jako typ mediów. Dźwięk steruje ruchem warg, gdy obecna jest twarz, a w przeciwnym razie ogólną energią ruchu.
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"]
Format audio ma znaczenie. WAV w mono 16kHz zapewnia najbardziej niezawodną synchronizację ruchu warg. MP3 o niższych przepływnościach dodaje artefakty, które model interpretuje jako energię ruchu, co objawia się niepożądanym ruchem głowy. Zachowaj krótkie prompty, to dźwięk wykonuje pracę.
W przypadku zastosowań typu "talking-head" łączy się to z klastrem wydajności postaci PixMind.
Jak wywołać R2V (referencja multimodalna)?
R2V (reference-to-video) to najpotężniejszy i najmniej udokumentowany tryb. Dokumentacja API Wan video-to-video akceptuje do pięciu obrazów referencyjnych, pięciu klipów referencyjnych i jednej ścieżki audio referencyjnej w jednym wywołaniu. Model wykorzystuje je do zachowania tożsamości, głosu i stylu w całym wyjściu.
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 ma limit 10 sekund, krócej niż 15-sekundowy limit T2V i I2V. Zachowanie tożsamości poprawia się wraz z większą liczbą obrazów referencyjnych do trzech, a następnie stabilizuje się. Dodanie klipów referencyjnych (krótkie ujęcia B-roll tego samego obiektu) zauważalnie zwiększa spójność ruchu.
[UNIKALNA WSKAZÓWKA] Dane wejściowe referencyjne to wagi, a nie ograniczenia. Jeśli obraz referencyjny przedstawia postać z przodu, a Twój prompt prosi o widok z boku, model połączy te dwa elementy, zamiast wybrać jeden. Traktuj referencje jako silne priory, a nie jako twarde cele.
R2V akceptuje do pięciu obrazów referencyjnych, pięciu klipów referencyjnych i jednego audio referencyjnego w jednym wywołaniu. Zachowanie tożsamości poprawia się wraz z liczbą obrazów referencyjnych do trzech, a następnie stabilizuje się, zgodnie z wewnętrznymi testami zgodnymi z dokumentacją API Wan video-to-video.
Aby uzyskać heurystyki wyboru trybu dla T2V, I2V i R2V, zobacz post PixMind o automatycznym routingu trybów.
Jak działa asynchroniczne odpytywanie zadań?
Wszystkie punkty końcowe Wan 2.7 są asynchroniczne. Wywołanie submit zwraca natychmiast task_id. Odpytujesz punkt końcowy zadania, aż status osiągnie stan końcowy. Przegląd generowania wideo wymienia pięć statusów: 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")
Dwie zasady odpytywania, które stosujemy w produkcji. Po pierwsze, używaj interwału 10 sekund. Szybsze odpytywanie spowoduje ograniczenie szybkości, a nie szybsze wyniki. Po drugie, ustaw limit czasu. 5-sekundowy render 1080P nie powinien trwać 10 minut; jeśli tak się dzieje, coś jest nie tak i powinieneś spróbować ponownie, zamiast czekać.
Punkty końcowe Wan 2.7 zwracają task_id i udostępniają punkt końcowy odpytywania pod adresem /api/v1/tasks/{task_id}. Statusy przechodzą przez PENDING, RUNNING, SUCCEEDED, FAILED i CANCELED, z zalecanym 10-sekundowym interwałem odpytywania zgodnie z przeglądem generowania wideo.
Jak obsługiwać błędy i ponawianie?
Błędy Wan 2.7 dzielą się na trzy kategorie. Błędy klienta (HTTP 4xx) oznaczają, że Twoje żądanie jest źle sformułowane lub nieautoryzowane, a ponowienie nie pomoże. Błędy serwera (HTTP 5xx) i przekroczenia limitu czasu są przejściowe. Błędy zadań (status: FAILED) mogą być przejściowe lub trwałe, w zależności od kodu błędu.
Przegląd generowania wideo dokumentuje typowe kody błędów. Najczęściej spotykane to:
| Kod | Znaczenie | Działanie |
|---|
| InvalidParameter.DownloadFailed | Adres URL wejściowy był nieosiągalny | Ponownie hostuj zasób i spróbuj ponownie |
| DataInsufficient.UnsafeContent | Prompt lub obraz oznaczony przez filtr bezpieczeństwa | Zmień dane wejściowe, nie próbuj ponownie |
| Throttling.RateQuota | Przekroczono QPS na klucz | Wykładnicze wycofywanie |
| InternalError.Timeout | Model przekroczył wewnętrzny limit czasu | Spróbuj ponownie raz |
| AccessDenied.Arrear | Konto bez środków | Doładuj, nie próbuj ponownie |
Wrapper do ponawiania z wykładniczym wycofywaniem:
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")
[ORYGINALNE DANE] Spośród 2000 śledzonych wywołań w lipcu 2026 roku, odnotowaliśmy 4,1 procent przejściowych błędów (HTTP 5xx, 429, błędy połączenia). Spośród nich, 91 procent zakończyło się sukcesem przy pierwszej próbie ponowienia, 6 procent przy drugiej, a 3 procent przy trzeciej. Ustaw liczbę ponowień na cztery i kontynuuj.
Ponawiaj tylko przejściowe błędy. HTTP 429 i 5xx można bezpiecznie ponawiać z wykładniczym wycofywaniem. W próbce 2000 wywołań z lipca 2026 roku, 4,1 procent było przejściowych, a 91 procent z nich zakończyło się sukcesem przy pierwszej próbie ponowienia (przegląd generowania wideo Alibaba Cloud).
Wan 2.7 API – często zadawane pytania
Jaki jest bazowy adres URL dla punktów końcowych Wan 2.7?
Punkty końcowe wideo Wan 2.7 znajdują się pod adresem https://dashscope.aliyuncs.com/api/v1/services/video-generation/. Punkt końcowy odpytywania zadań to https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}. Oba są udokumentowane w przeglądzie generowania wideo.
Czy istnieje oficjalne SDK dla Pythona?
Alibaba dostarcza DashScope Python SDK (dashscope) na PyPI. Przykłady w tym przewodniku używają requests dla przenośności. Jeśli wolisz SDK, równoważne wywołanie to dashscope.VideoGeneration.call(model="wan2.7-t2v", ...).
Czy mogę anulować zadanie w toku?
Tak. Żądanie POST do /api/v1/tasks/{task_id}/cancel oznacza zadanie jako CANCELED. Zostaniesz obciążony za już zużyte zasoby obliczeniowe, więc anulowanie to obszar częściowego zwrotu kosztów, a nie darmowe.
Ile czasu zajmuje renderowanie R2V?
R2V jest wolniejsze niż T2V i I2V przy tej samej rozdzielczości i czasie trwania. 5-sekundowy render R2V w 1080P z trzema obrazami referencyjnymi uśrednia 110 sekund w naszych testach, w porównaniu do 78 sekund dla T2V. Odpowiednio zaplanuj limity czasu.
Czy punkty końcowe Wan 2.7 obsługują webhooki?
Nie natywnie. Musisz odpytywać. Jeśli potrzebujesz dostarczania w stylu webhooka, opakuj pętlę odpytywania w usługę, która wysyła dane na Twój adres URL zwrotny po zakończeniu zadania.
Zobacz w akcji
Powiązane na X: OpenRouter — Ogłoszenie integracji API OpenRouter dla Wan 2.7..
