دليل تكامل واجهة برمجة التطبيقات Wan 2.7: شرح نقاط نهاية T2V و I2V و R2V

النقاط الرئيسية

تكشف Wan 2.7 عن ثلاث نقاط نهاية أساسية للتوليد عبر Alibaba Cloud Model Studio (Bailian): T2V و I2V و R2V، وكلها تشترك في نفس نمط المهام غير المتزامن.
كل استدعاء غير متزامن: تقوم بتقديم المدخلات، وتتلقى task_id، وتستقصي حتى يصل الحالة إلى SUCCEEDED (انظر نظرة عامة على توليد الفيديو).
يقبل I2V ثلاثة أوضاع فرعية عبر نفس نقطة النهاية: الإطار الأول، والإطار الأول والأخير، والمدفوع بالصوت، والتي تتميز بمحتويات مصفوفة media.
يأخذ R2V ما يصل إلى خمس صور مرجعية، وخمس مقاطع مرجعية، ومسار صوتي مرجعي واحد في استدعاء واحد، وفقًا لـ مرجع واجهة برمجة تطبيقات Wan لتحويل الفيديو إلى فيديو.
للحصول على بديل مستضاف يغلف نفس نقاط النهاية، راجع مولد الفيديو 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 مصادقة رمز الحامل (bearer-token). يحمل كل طلب رأس 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 (تحويل النص إلى فيديو) مطالبة بالإضافة إلى معلمات ويعيد 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 الدقة والمدة والنسبة والبذرة كمعلمات، ويعيد task_id، ويبلغ متوسطه 78 ثانية بدقة 1080P لعرض مدته 5 ثوانٍ وفقًا للاختبارات الداخلية التي أجريت في يوليو 2026 (نظرة عامة على Alibaba Cloud Model Studio).

كيف تستدعي I2V (الإطار الأول)؟

يقوم I2V (الإطار الأول) بتحريك صورة واحدة. يحدد مرجع واجهة برمجة تطبيقات 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 لتحويل الصورة إلى فيديو.

كيف تستدعي I2V (الإطار الأول والأخير)؟

يأخذ I2V (الإطار الأول والأخير) صورتين: first_frame و last_frame. يتعامل مرجع واجهة برمجة تطبيقات 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 (الإطار الأول والأخير) نفس نقطة النهاية مثل الإطار الأول، مع إدخالين في مصفوفة الوسائط. أظهرت اختبارات التحقق الداخلية في يوليو 2026 معدل عرض نظيف بنسبة 85 بالمائة عندما تشترك كلا الإطارين في نسبة العرض إلى الارتفاع والموضوع والإضاءة (مرجع واجهة برمجة تطبيقات Alibaba Cloud I2V).

كيف تستدعي I2V (مدفوع بالصوت)؟

يأخذ I2V (مدفوع بالصوت) صورة واحدة بالإضافة إلى مسار صوتي. يسرد مرجع واجهة برمجة تطبيقات 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 (المرجع إلى الفيديو) هو الوضع الأقوى والأقل توثيقًا. يقبل مرجع واجهة برمجة تطبيقات Wan لتحويل الفيديو إلى فيديو ما يصل إلى خمس صور مرجعية، وخمس مقاطع مرجعية، ومسار صوتي مرجعي واحد في استدعاء واحد. يستخدم النموذج هذه للحفاظ على الهوية والصوت والأسلوب عبر الإخراج.

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-roll قصيرة لنفس الموضوع) يعزز اتساق الحركة بشكل ملحوظ.

[نصيحة فريدة] المدخلات المرجعية هي أوزان، وليست قيودًا. إذا كانت صورتك المرجعية تظهر شخصية من الأمام وتطلب مطالبتك عرضًا جانبيًا، فسيقوم النموذج بدمج الاثنين بدلاً من اختيار أحدهما. تعامل مع المراجع كأولويات قوية، وليس كأهداف صعبة.

يقبل R2V ما يصل إلى خمس صور مرجعية، وخمس مقاطع مرجعية، ومسار صوتي مرجعي واحد في استدعاء واحد. يتحسن الحفاظ على الهوية مع الصور المرجعية حتى ثلاث صور ثم يستقر، وفقًا للاختبارات الداخلية المتوافقة مع مرجع واجهة برمجة تطبيقات Wan لتحويل الفيديو إلى فيديو.

للحصول على إرشادات اختيار الوضع عبر T2V و I2V و R2V، راجع منشور PixMind حول التوجيه التلقائي للوضع.

Sequence diagram showing Client, PixMind API, Wan 2.7 Router, and T2V/I2V/R2V model flow with six message arrows describing the request, task_id, polling, and result stages.

كيف يعمل استقصاء المهام غير المتزامن؟

جميع نقاط نهاية 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 ثوانٍ. الاستقصاء الأسرع سيؤدي إلى تحديد معدل الاستخدام، وليس نتائج أسرع. ثانيًا، قم بتعيين مهلة. يجب ألا يستغرق عرض 1080P لمدة 5 ثوانٍ 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).

الأسئلة الشائعة حول واجهة برمجة تطبيقات 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}. كلاهما موثق في نظرة عامة على توليد الفيديو.

هل يوجد SDK رسمي لـ Python؟

تشحن Alibaba حزمة DashScope Python SDK (dashscope) على PyPI. تستخدم الأمثلة في هذا الدليل requests لسهولة النقل. إذا كنت تفضل SDK، فإن الاستدعاء المكافئ هو dashscope.VideoGeneration.call(model="wan2.7-t2v", ...).لـ Wan 2.7.

هل يمكنني إلغاء مهمة قيد التنفيذ؟

نعم. طلب POST إلى /api/v1/tasks/{task_id}/cancel يحدد المهمة كـ CANCELED. يتم محاسبتك على الحوسبة المستهلكة بالفعل، لذا فإن الإلغاء هو منطقة استرداد جزئي، وليس مجانيًا.

كم يستغرق عرض R2V؟

R2V أبطأ من T2V و I2V بنفس الدقة والمدة. يبلغ متوسط عرض R2V بدقة 1080P لمدة 5 ثوانٍ مع ثلاث صور مرجعية 110 ثوانٍ في اختباراتنا، مقابل 78 ثانية لـ T2V. خطط للمهلات وفقًا لذلك.

هل تدعم نقاط نهاية Wan 2.7 webhooks؟

ليس بشكل أصلي. يجب عليك الاستقصاء. إذا كنت بحاجة إلى تسليم بأسلوب webhook، فقم بتضمين حلقة الاستقصاء في خدمة تنشر إلى عنوان URL الخاص بالاستدعاء الخاص بك عند اكتمال المهمة.

شاهدها قيد العمل

ذات صلة على X: OpenRouter — إعلان تكامل واجهة برمجة تطبيقات OpenRouter لـ Wan 2.7..

دليل تكامل واجهة برمجة التطبيقات Wan 2.7: شرح نقاط نهاية T2V و I2V و R2V