تنقسم أخطاء Seedance إلى طبقتين: طبقة فشل طلب HTTP مثل 401 و403 و400 و429؛ وطبقة نجاح الطلب مع انتهاء المهمة في النهاية إلى failed أو expired. اعتبار الاستجابة 200 من واجهة الإرسال نجاحًا هو أكثر الأخطاء شيوعًا عند ربط واجهات الفيديو. الترتيب الصحيح: افحص رمز HTTP أولًا، ثم حالة المهمة وحقل error، ولا تعدّل المطالبة أو تغيّر النموذج إلا في النهاية.

يقسم هذا المقال الأخطاء حسب النوع ويعرض الأسباب وترتيب المعالجة وشيفرة قابلة لإعادة الاستخدام. مسارات الواجهة وتسمية الحالات وقواعد الحصص قد تتغير مع الإصدارات، والمرجع الفعلي وثائق الموقع والوثائق الرسمية.

ملاحظة: Seedance وDoubao وVolcengine علامات تجارية لشركة ByteDance والشركات التابعة لها. هذا المقال تقني فقط، ولا يمثل أي تبعية أو تأييد. المسارات والحقول في الأمثلة للتوضيح فقط، لذا راجع الوثائق قبل الاستدعاء.

أولًا: ميّز فشل الطلب من فشل المهمة

الظاهرة الطبقة السبب الشائع المعالجة
401 HTTP مفتاح مفقود أو تنسيقه خاطئ أو منتهٍ إصلاح المصادقة
403 HTTP صلاحية غير كافية، نموذج غير مفعّل، قيد منطقة فحص الصلاحية وحالة التفعيل
400 HTTP معامل خارج النطاق، اسم نموذج خاطئ، مادة غير قابلة للوصول تعديل المعامل وفق الوثائق
429 HTTP تقييد التزامن أو السرعة أو الحصة التباعد وخفض التزامن
5xx HTTP حمل زائد في المنبع أو عطل مؤقت التباعد وتبديل القناة
failed المهمة رفض مراجعة، مشكلة مادة، خلل توليد قراءة error وإصلاح المادة
expired المهمة انتهاء المدة دون اكتمال أو دون استلام النتيجة إعادة إنشاء المهمة وفحص المدة
فشل التنزيل النتيجة انتهاء صلاحية URL، مصادقة، شبكة إعادة الحصول أو النقل إلى مخزن

تسجل السجلات على الأقل الوقت ورمز HTTP ورمز الخطأ واسم النموذج وtask_id ورقم العملية والمدة. لا تسجل المفتاح كاملًا، ولا تطبع رابط النتيجة الموقّع كما هو.

ثانيًا: 401 و403: افحص الترويسة والمفتاح أولًا

يعني 401 أن الهوية لم تجتز التحقق، ولا علاقة له عادة بقدرات النموذج أو الرصيد. افحص بالترتيب:

  • هل Authorization بالشكل Bearer <key>، فـ Volcano Ark يستخدم مفتاح API كرمز Bearer.
  • هل يحمل المفتاح مسافات أو أسطرًا جديدة أو علامات اقتباس زائدة، وهل حُمل متغير البيئة فعلًا.
  • هل Base URL والمفتاح من المنصة والمنطقة نفسها.
  • هل حُذف المفتاح أو دُوّر أو أُوقف، أو صلاحيات المشروع غير كافية.
  • هل يغطي الوسيط العكسي ترويسة Authorization أو يحذفها.

يعني 403 غالبًا مشكلة صلاحيات: نموذج غير مفعّل، أو الحساب لا يملك صلاحية النموذج، أو قيد منطقة أو امتثال. 401 يُحدد سريعًا بمفتاح جديد وطلب أدنى؛ أما 403 فيتطلب فحص حالة التفعيل وصلاحيات الحساب في لوحة التحكم، وتعديل الكود لا يفيد عادة.

ثالثًا: 429: الحد والتزامن والحصة

يعني 429 تجاوز حد السرعة أو التزامن أو الحصة. السيناريوهات الشائعة:

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

المبدأ: تباعد أُسّي مع تذبذب عشوائي، وخفض التزامن، وفصل المفاتيح حسب المشروع، وتوزيع الإرسال خارج الذروة. لا تكرر في حلقة بلا تباعد؛ فالإرسال الكثيف خلال 429 يحول الحد المؤقت إلى عطل مستمر. وإذا احتاج العمل تزامنًا عاليًا فعلًا، فتأكد من سقف الحصة مسبقًا وجهّز قناة بديلة.

رابعًا: 400: أخطاء المعاملات هي الأغلبية

يمكن تحديد 400 عادة من رسالة الخطأ مباشرة، وركز على:

  • اسم النموذج والإصدار: انسخه من الوثائق ولا تبنِ اللاحقة من الذاكرة.
  • المدة: تختلف النطاقات حسب الطراز، فمثلًا 2.5 من 4 إلى 30 ثانية، و2.0 من 4 إلى 15 ثانية، و1.0 من 2 إلى 12 ثانية.
  • الدقة والنسبة: تأكد هل يدعم النموذج 4K أو 21:9 أو adaptive.
  • عدد المواد المرجعية: 2.5 يدعم حتى 30 صورة و10 مقاطع فيديو و10 مقاطع صوتية؛ وسقف 2.0 أقل.
  • روابط الصور أو الفيديو: يجب أن تكون متاحة للمنصة، لا عنوانًا داخليًا أو رابطًا يحتاج تسجيل دخول.
  • مهام التحرير أو الاستكمال: بعض الأوضاع تسمح بالمدة التلقائية فقط ولا تقبل إدخال الثواني يدويًا.
  • الإدخال الصوتي: بعض الإصدارات لا تدعم الإدخال الصوتي المحض.

أسرع طريقة هي إعادة إنتاج طلب أدنى بجسم المثال في الوثائق، ثم إعادة إضافة معاملاتك واحدًا واحدًا. كل إضافة مع اختبار تحدد الحقل المسؤول.

خامسًا: المهام failed وexpired

نجاح الإرسال يعني دخول المهمة الصف فقط. تشمل الحالات الشائعة في نتيجة الاستعلام queued وrunning وsucceeded وfailed وexpired. في failed اقرأ حقل error: رفض مراجعة المحتوى، مادة إدخال غير متوافقة، تعذر قراءة الصورة المرجعية، خلل أثناء التوليد؛ والمعالجة تختلف تمامًا.

يظهر expired عادة عندما تتجاوز المهمة مدة التنفيذ دون اكتمال أو دون استلام النتيجة. في الوثائق يمكن ضبط execution_expires_after، والقيمة الافتراضية 48 ساعة؛ ويُحتفظ بمعرّف المهمة 7 أيام. بعد انتهاء المدة لا يعيد الاستعلام المتكرر المهمة، بل يجب إعادة إنشائها. عند استخدام رد الاتصال انتبه: إذا لم يُؤكد خلال 5 ثوانٍ يُعاد الإرسال 3 مرات، لذا يجب أن تكون واجهة الرد متكررة الأمان.

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

سادسًا: المهلة والاستعلام المتكرر

تنقسم المهلة إلى ثلاث طبقات: مهلة اتصال العميل، ومهلة الاستعلام الواحد، والموعد النهائي الكلي للمهمة. تعيد واجهة الإرسال task_id عادة بسرعة، والوقت الحقيقي يذهب إلى الصف والعرض. مهلة قصيرة جدًا في عميل HTTP تحوّل إرسالًا سليمًا إلى فشل وهمي؛ وطويلة جدًا تحتجز مجمع الخيوط.

يُقترح بدء الاستعلام بعد 5 ثوانٍ ثم التباعد تدريجيًا إلى 15–30 ثانية مع موعد نهائي كلي. عند دعم رد الاتصال يُفضّل استخدامه، ويبقى الاستعلام كخيار احتياطي. لا تعد الإرسال فور انتهاء المهلة، بل افحص برقم العملية أو مفتاح عدم التكرار هل توجد مهمة قيد التشغيل.

سابعًا: فشل تنزيل النتيجة

نجاح المهمة لا يعني وصول الملف. غالبًا يكون video_url عنوانًا مؤقتًا موقّعًا له صلاحية؛ وتخزينه مباشرة ثم تنزيله بعد ساعات يعيد 403 أو 404. المعالجة:

  • نزّل فورًا بعد النجاح بشكل متدفق إلى مخزن الكائنات الخاص بك.
  • أعد المحاولة للتنزيل الفاشل وحده، ولا تعد إنشاء مهمة التوليد.
  • تحقق من Content-Type وحجم الملف وقابلية التشغيل.
  • لا تطبع الرابط الموقّع كاملًا في السجلات.

ثامنًا: مثال: معالجة أخطاء مع تباعد وعدم تكرار

تفصل الشيفرة التالية الإرسال والاستعلام والتنزيل، وتعيد المحاولة فقط في الأخطاء العابرة. المسارات والحقول مرجعها وثائق الموقع.

import os, time, random, requests

BASE = os.environ["SEEDANCE_BASE_URL"].rstrip("/")
HEADERS = {
    "Authorization": f"Bearer {os.environ['SEEDANCE_API_KEY']}",
    "Content-Type": "application/json",
}

def submit(payload, max_retries=5):
    # قبل الاستدعاء ابحث في جدول المهام برقم العملية؛ إن وجدت task_id فأعد استخدامه
    for attempt in range(max_retries):
        try:
            r = requests.post(
                f"{BASE}/contents/generations/tasks",
                headers=HEADERS, json=payload, timeout=(5, 30),
            )
        except requests.Timeout:
            time.sleep(min(2 ** attempt, 20) + random.random())
            continue
        if r.status_code == 429 or r.status_code >= 500:
            time.sleep(min(2 ** attempt, 20) + random.random())
            continue
        if r.status_code >= 400:
            raise RuntimeError(f"{r.status_code}: {r.text[:500]}")
        return r.json()["id"]
    raise RuntimeError("submit retries exhausted")

def wait(task_id, deadline_seconds=900):
    deadline = time.time() + deadline_seconds
    delay = 5
    while time.time() < deadline:
        r = requests.get(
            f"{BASE}/contents/generations/tasks/{task_id}",
            headers=HEADERS, timeout=(5, 30),
        )
        if r.status_code == 429 or r.status_code >= 500:
            time.sleep(delay)
            delay = min(delay * 1.5, 30)
            continue
        r.raise_for_status()
        data = r.json()
        if data["status"] == "succeeded":
            return data["content"]["video_url"]
        if data["status"] in ("failed", "expired"):
            raise RuntimeError(f"{data['status']}: {data.get('error')}")
        time.sleep(delay)
        delay = min(delay * 1.5, 30)
    raise TimeoutError(task_id)

def download(url, path):
    with requests.get(url, stream=True, timeout=(5, 120)) as r:
        r.raise_for_status()
        with open(path, "wb") as f:
            for chunk in r.iter_content(1024 * 256):
                f.write(chunk)

تتعمد الشيفرة عدم إعادة المحاولة في 400 و401 و403. أخطاء المعاملات والمصادقة لن تنجح مهما تكررت، وستضخم السجلات والتكاليف فقط.

تاسعًا: إعادة المحاولة وعدم التكرار وقائمة الدعم

إعادة المحاولة تصلح فقط للأخطاء العابرة: 429 و5xx ومهلة الاتصال. لا يُعاد تلقائيًا 400 و401 و403 ورفض المراجعة. مفتاح عدم التكرار الحقيقي ليس عدد المحاولات، بل رقم العملية: افحص جدول المهام قبل الإرسال، وسجّل task_id بعده، وأعد استخدام المهمة القائمة للطلب المكرر.

قبل مخاطبة مزوّد الخدمة رتب المعلومات وفق القائمة:

  1. وقت الحدوث ورمز HTTP ورمز الخطأ ورسالة الخطأ الكاملة مع إخفاء الحساس.
  2. اسم النموذج والمدة والدقة والنسبة وعدد المواد المرجعية.
  3. task_id ورقم العملية وعدد مرات الإرسال والاستعلام.
  4. احتفظ بطلب إعادة إنتاج أدنى دون خصوصية المستخدم والمفاتيح.
  5. ميّز فشل الطلب من فشل المهمة failed أو expired.
  6. افحص هل رابط المادة متاح علنًا، وهل الاستجابة بطيئة.
  7. تأكد من الحصة والتزامن وصلاحيات الحساب لاستبعاد 429 و403.
  8. أرفق معرّف الطلب ووقت إعادة الإنتاج قبل تقديم البلاغ.

الأسئلة الشائعة

لماذا تفشل المهمة رغم أن الإرسال أعاد 200؟

200 يعني نجاح إنشاء المهمة فقط. توليد الفيديو غير متزامن، والحالة النهائية تُقرأ من status وerror في نتيجة الاستعلام.

هل 429 يعني نقص الرصيد؟

ليس بالضرورة. 429 يعني عادة تقييد السرعة أو التزامن أو الحصة، وقد يعيد نقص الرصيد خطأ آخر. افحص التزامن والمفاتيح المشتركة واستراتيجية إعادة المحاولة أولًا.

هل يمكن إعادة المحاولة مباشرة بعد failed؟

اقرأ error أولًا. رفض المراجعة وعدم توافق المادة سيفشلان غالبًا كما هما؛ وأعطال الشبكة أو المنبع يمكن إعادة المحاولة فيها بتباعد. افحص عدم التكرار برقم العملية قبل الإرسال.

كم مرة نستعلم عن المهمة؟

ابدأ من 5 ثوانٍ ثم تباعد تدريجيًا إلى 15–30 ثانية، مع مهلة كلية. عند دعم رد الاتصال يُفضّل استخدامه ويبقى الاستعلام احتياطًا.

ماذا نفعل إذا تعذر فتح رابط النتيجة؟

غالبًا انتهت صلاحيته أو فشل التوقيع. انقل النتيجة فورًا إلى مخزن الكائنات بعد النجاح؛ وإذا انتهت الصلاحية فأعد استعلام المهمة أو أنشئها من جديد، ولا تكرر طلب الرابط القديم.

الخطوة التالية

أنشئ مفتاح اختبار في ZSQH AI Gateway، ونفّذ تمرينًا على 401 و429 وأخطاء المعاملات وفشل المهمة، وتأكد من فعالية التنبيهات واستراتيجية إعادة المحاولة. توفر النماذج وطريقة الفوترة في أسعار النماذج.

قراءات ذات صلة: