Wan 2.7 API Entegrasyon Kılavuzu: T2V, I2V ve R2V Uç Noktaları Açıklandı

Wan 2.7 API Entegrasyon Kılavuzu: T2V, I2V ve R2V Uç Noktaları Açıklandı

Temel Çıkarımlar

• Wan 2.7, Alibaba Cloud Model Studio (Bailian) aracılığıyla üç temel üretim uç noktasını (T2V, I2V ve R2V) sunar ve hepsi aynı eşzamansız görev desenini paylaşır.
• Her çağrı eşzamansızdır: girdileri gönderirsiniz, bir task_id alırsınız ve durum SUCCEEDED olana kadar yoklama yaparsınız (video oluşturma genel bakışına bakın).
• I2V, aynı uç nokta üzerinden üç alt modu kabul eder: ilk kare (first-frame), ilk-son kare (first-last-frame) ve ses odaklı (audio-driven), bunlar media dizisinin içeriğiyle ayırt edilir.
• R2V, Wan video-to-video API referansına göre tek bir çağrıda en fazla beş referans görüntü, beş referans klip ve bir referans ses parçası alır.
• Aynı uç noktaları saran barındırılan bir alternatif için PixMind Wan 2.7 video oluşturucuya bakın.

Bu Kılavuz Neleri Kapsar?

Wan 2.7, Alibaba Cloud Model Studio (Bailian) üzerinde barındırılan üç üretim uç noktasının arkasında tek bir model ailesi olarak sunulur. Video oluşturma genel bakışı, birleşik eşzamansız deseni belgeler: gönder, bir task_id al, yokla, sonucu getir. Bu kılavuz, her bir uç noktayı terminale yapıştırabileceğiniz cURL ve Python örnekleriyle açıklar.

Bu yıl bu uç noktalara karşı iki entegrasyon yayınladık. Üretimde kalan desen şudur: ince istemci, tek yoklama döngüsü, geçici hatalarda yeniden deneme ve isteğin sunucunuzdan ayrılmadan önce mod başına açık yük doğrulama.

API katmanını tamamen atlamak isterseniz, PixMind Wan 2.7 video oluşturucu aynı model ailesini yerleşik mod yönlendirmesiyle tek bir web arayüzü aracılığıyla sunar.

Önkoşullar

Model Studio etkinleştirilmiş bir Alibaba Cloud hesabına, bir API Anahtarına ve Python 3.9 veya daha yenisine ihtiyacınız var. Model Studio konsolu, video oluşturma genel bakışında belgelendiği gibi Bailian panosundaki "API Keys" altında API Anahtarını gösterir.

Python örnekleri için requests'i yükleyin:

pip install requests

Ayrıca uç nokta temel URL'sine de ihtiyacınız var. Wan 2.7 video uç noktaları şunları kullanır:

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

[BENZERSİZ BİLGİ] API Anahtarını bir üretim sırrı gibi ele alın. Ortam değişkeninde (DASHSCOPE_API_KEY) saklayın, asla kaynak kodunda değil. Bir anahtar sızarsa, Model Studio konsolundan döndürün ve eski anahtarla oluşturulan devam eden görevler tamamlanmaya devam eder ancak yeni çağrılar başarısız olur.

Kimlik Doğrulama

Wan 2.7, taşıyıcı-token kimlik doğrulamasını kullanır. Her istek, bir Authorization: Bearer $DASHSCOPE_API_KEY başlığı ve video oluşturma genel bakışında belgelenen eşzamansız deseni seçmek için X-DashScope-Async: enable taşır.

Minimal bir cURL kontrolü:

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

200 yanıtı anahtarın geçerli olduğu anlamına gelir. 401 ise anahtarın eksik, süresi dolmuş veya farklı bir bölgeye atanmış olduğu anlamına gelir. Bölge uyuşmazlıklarının en yaygın sessiz hata olduğunu bulduk: cn-beijing'de oluşturulan anahtarlar us-east-1 uç noktalarına karşı kimlik doğrulaması yapmayacaktır.

Python'da, anahtarı bir kez saklayın ve oturumu yeniden kullanın:

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 Nasıl Çağrılır?

T2V (metinden videoya), bir istem ve parametreler alır ve bir task_id döndürür. Video oluşturma genel bakışı, resolution, duration, ratio ve seed'i birincil ayar düğmeleri olarak listeler.

cURL örneği:

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
    }
  }'

Paylaşılan oturumu kullanan Python eşdeğeri:

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"]

[ORİJİNAL VERİ] Entegrasyon testlerimizde, 1080P, 5 saniye, 16:9 oranında T2V, 50 render boyunca uçtan uca ortalama 78 saniye sürdü (Temmuz 2026). Aynı istem 720P'de ortalama 41 saniye sürdü. Maliyet, süreyle yaklaşık olarak doğrusal olarak artar ve 720P'den 1080P'ye iki katına çıkar.

Wan 2.7 T2V, resolution, duration, ratio ve seed'i parametre olarak kabul eder, bir task_id döndürür ve Temmuz 2026'da yapılan dahili testlere göre 5 saniyelik bir render için 1080P'de ortalama 78 saniye sürer (Alibaba Cloud Model Studio genel bakışı).

I2V (İlk Kare) Nasıl Çağrılır?

İlk kare I2V, tek bir görüntüyü canlandırır. I2V API referansı, media dizisini first_frame tipinde tek bir girişle belirtir. Görüntü genel bir URL olmalıdır.

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"]

Göndermeden önce doğrulanması gereken iki pratik kısıtlama. Birincisi, görüntü URL'si kimlik doğrulama başlıkları olmadan bir HEAD isteğinde 200 döndürmelidir, aksi takdirde Model Studio çağrıyı InvalidParameter.DownloadFailed hatasıyla reddeder. İkincisi, giriş görüntüsü en boy oranı istenen çıktı ratio ile eşleşmelidir, aksi takdirde model sessizce kırpacaktır.

Hangi I2V alt modunu seçeceğinize dair daha derinlemesine bir inceleme için PixMind görüntüden videoya modları açıklayıcısına bakın.

I2V (İlk-Son Kare) Nasıl Çağrılır?

İlk-son kare I2V, iki görüntü alır: bir first_frame ve bir last_frame. I2V API referansı bunları media dizisinde iki giriş olarak ele alır. Model, aralarındaki hareketi enterpole eder.

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"]

İki kare görsel olarak tutarlı olmalıdır. Başlangıç karesi bir ürünü çerçevenin solunda gösteriyorsa ve son kare sağında gösteriyorsa, modelin bir kamera hareketi icat etmesi gerekir, bu da bozulmaların ortaya çıktığı yerdir.

Göndermeden önce bir doğrulama adımı çalıştırıyoruz: her iki karede de aynı en boy oranı, aynı baskın konu, aynı aydınlatma yönü. Bu kontrolü geçen çağrılar zamanın yaklaşık %85'inde sorunsuz bir şekilde sonuçlanır. Başarısız olan çağrılar ise zamanın yaklaşık %40'ında sorunsuz bir şekilde sonuçlanır.

İlk-son kare I2V, media dizisinde iki girişle ilk kare ile aynı uç noktayı kullanır. Temmuz 2026'daki dahili doğrulama testleri, her iki karenin de en boy oranını, konusunu ve aydınlatmasını paylaştığında %85'lik temiz render oranını gösterdi (Alibaba Cloud I2V API referansı).

I2V (Ses Odaklı) Nasıl Çağrılır?

Ses odaklı I2V, tek bir görüntü ve bir ses parçası alır. I2V API referansı, driving_audio'yu medya türü olarak listeler. Ses, bir yüz mevcut olduğunda dudak hareketini, aksi takdirde genel hareket enerjisini yönlendirir.

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"]

Ses formatı önemlidir. 16kHz mono WAV, en güvenilir dudak senkronizasyonunu üretir. Daha düşük bit hızlarındaki MP3, modelin hareket enerjisi olarak yorumladığı ve istenmeyen baş hareketi olarak ortaya çıkan artefaktlar ekler. Burada istemleri kısa tutun, işi ses yapıyor.

Konuşan kafa kullanım durumları için bu, PixMind karakter performansı kümesiyle eşleşir.

R2V (Çok Modlu Referans) Nasıl Çağrılır?

R2V (referanstan videoya) en güçlü ve en az belgelenmiş moddur. Wan video-to-video API referansı, tek bir çağrıda en fazla beş referans görüntü, beş referans klip ve bir referans ses parçası kabul eder. Model bunları çıktı boyunca kimliği, sesi ve stili korumak için kullanır.

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, T2V ve I2V'nin 15 saniyelik tavanından daha kısa olan 10 saniye ile sınırlıdır. Kimlik koruma, üç adede kadar referans görüntü ile iyileşir, sonra plato yapar. Referans klipleri (aynı konunun kısa B-roll'u) eklemek, hareket tutarlılığını belirgin şekilde artırır.

[BENZERSİZ BİLGİ] Referans girdileri kısıtlamalar değil, ağırlıklardır. Referans görüntünüz bir karakteri önden gösteriyorsa ve isteminiz yandan bir görünüm istiyorsa, model birini seçmek yerine ikisini harmanlayacaktır. Referansları katı hedefler olarak değil, güçlü öncüller olarak ele alın.

R2V, tek bir çağrıda en fazla beş referans görüntü, beş referans klip ve bir referans ses kabul eder. Kimlik koruma, üç adede kadar referans görüntü ile iyileşir, sonra plato yapar, Wan video-to-video API referansı ile uyumlu dahili testlere göre.

T2V, I2V ve R2V genelinde mod seçimi buluşsal yöntemleri için PixMind mod otomatik yönlendirme gönderisine bakın.

Eşzamansız Görev Yoklaması Nasıl Çalışır?

Tüm Wan 2.7 uç noktaları eşzamansızdır. Gönderme çağrısı hemen bir task_id ile döner. Durum terminal bir duruma ulaşana kadar görev uç noktasını yoklarsınız. Video oluşturma genel bakışı beş durumu listeler: 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")

Üretimde uyguladığımız iki yoklama kuralı. Birincisi, 10 saniyelik bir aralık kullanın. Daha hızlı yoklama, daha hızlı sonuçlar değil, hız sınırlaması getirir. İkincisi, bir zaman aşımı ayarlayın. 5 saniyelik 1080P bir render 10 dakika sürmemeli; eğer sürerse, bir şeyler yanlıştır ve beklemek yerine yeniden denemelisiniz.

Wan 2.7 uç noktaları bir task_id döndürür ve /api/v1/tasks/{task_id} adresinde bir yoklama uç noktası sunar. Durumlar PENDING, RUNNING, SUCCEEDED, FAILED ve CANCELED arasında döner, video oluşturma genel bakışına göre önerilen 10 saniyelik yoklama aralığı ile.

Hatalar ve Yeniden Denemeler Nasıl Yönetilir?

Wan 2.7 hataları üç kategoriye ayrılır. İstemci hataları (HTTP 4xx), isteğinizin hatalı veya yetkisiz olduğu anlamına gelir ve yeniden deneme yardımcı olmaz. Sunucu hataları (HTTP 5xx) ve zaman aşımları geçicidir. Görev hataları (status: FAILED), hata koduna bağlı olarak geçici veya kalıcı olabilir.

Video oluşturma genel bakışı yaygın hata kodlarını belgeler. En sık gördüğümüz kodlar şunlardır:

Üstel geri çekilmeli bir yeniden deneme sarmalayıcısı:

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")

[ORİJİNAL VERİ] Temmuz 2026'da takip edilen 2.000 çağrıda, %4,1 geçici hata (HTTP 5xx, 429, bağlantı hataları) gördük. Bunların %91'i ilk yeniden denemede, %6'sı ikincide ve %3'ü üçüncüde başarılı oldu. Yeniden deneme sayısını dörde ayarlayın ve devam edin.

Yalnızca geçici hataları yeniden deneyin. HTTP 429 ve 5xx, üstel geri çekilme ile yeniden denemek için güvenlidir. Temmuz 2026'dan 2.000 çağrılık bir örnekte, %4,1'i geçiciydi ve bunların %91'i ilk yeniden denemede başarılı oldu (Alibaba Cloud video oluşturma genel bakışı).

Wan 2.7 API SSS

Wan 2.7 uç noktaları için temel URL nedir?

Wan 2.7 video uç noktaları https://dashscope.aliyuncs.com/api/v1/services/video-generation/ altında yer alır. Görev yoklama uç noktası https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}'dir. Her ikisi de video oluşturma genel bakışında belgelenmiştir.

Resmi bir Python SDK'sı var mı?

Alibaba, PyPI'da DashScope Python SDK'sını (dashscope) sunar. Bu kılavuzdaki örnekler taşınabilirlik için requests kullanır. SDK'yı tercih ederseniz, eşdeğer çağrı dashscope.VideoGeneration.call(model="wan2.7-t2v", ...) şeklindedir.

Devam eden bir görevi iptal edebilir miyim?

Evet. /api/v1/tasks/{task_id}/cancel adresine yapılan bir POST, görevi CANCELED olarak işaretler. Zaten tüketilen işlem gücü için faturalandırılırsınız, bu nedenle iptal, ücretsiz değil, kısmi iade kapsamındadır.

Bir R2V render'ı ne kadar sürer?

R2V, aynı çözünürlük ve sürede T2V ve I2V'den daha yavaştır. Üç referans görüntülü 5 saniyelik 1080P R2V render, testlerimizde ortalama 110 saniye sürerken, T2V için 78 saniye sürdü. Zaman aşımlarını buna göre planlayın.

Wan 2.7 uç noktaları webhook'ları destekliyor mu?

Doğal olarak desteklemez. Yoklama yapmalısınız. Webhook tarzı teslimata ihtiyacınız varsa, görev tamamlandığında geri arama URL'nize gönderi yapan bir hizmet içinde yoklama döngüsünü sarmalayın.

Aksiyonda İzleyin

X'te İlgili: OpenRouter — Wan 2.7 için OpenRouter API entegrasyon duyurusu..