واجهة برمجة تطبيقات (API) إنشاء الصور غير المتزامنة: المهام (Jobs)، والاستقصاء (Polling)، وخطافات الويب (Webhooks)، وإعادة المحاولة (Retries)

تتيح لك واجهة برمجة تطبيقات توليد الصور غير المتزامنة إرسال طلب توليد، والحصول على معرف مهمة (job identifier) على الفور، واسترداد الصورة النهائية لاحقاً بدلاً من إبقاء اتصال HTTP مفتوحاً. يغطي هذا الدليل دورة حياة المهمة، ومتى يجب استخدام الاستطلاع مقابل خطافات الويب، وكيفية تصميم عمليات إعادة المحاولة حتى لا تؤدي المهمة البطيئة أو الفاشلة إلى الإضرار بتجربة منتجك.

أبرز النقاط

• تعتمد عملية توليد الصور على نظام المهام (job-based) وليس على نمط الطلب والاستجابة (request-response)، لأن زمن انتقال التوليد (من ثوانٍ إلى عشرات الثواني) يجعل من غير الموثوق إبقاء اتصال متزامن مفتوحاً.
• يعد الاستطلاع (Polling) أسهل في البناء والتصحيح؛ بينما تقلل خطافات الويب (Webhooks) من زمن الانتقال وحجم الطلبات، لكنها تتطلب نقطة نهاية عامة (public endpoint)، والتحقق من التوقيع، ومعالجة متكررة (idempotent) لعمليات التسليم المكررة.
• يجب أن تميز منطق إعادة المحاولة بين فشل الإرسال، والمهام العالقة، وعمليات تسليم خطافات الويب المفقودة؛ حيث يحتاج كل منها إلى مسار استرداد مختلف.
• تختلف أسماء نقاط النهاية الدقيقة، وأسماء الحقول، وأشكال حمولة خطافات الويب حسب المزود وحسب واجهة API الخاصة بـ TokenLab. تأكد دائماً من التفاصيل الحالية عبر docs.tokenlab.sh قبل الإطلاق.

لماذا تعتبر واجهات برمجة تطبيقات توليد الصور غير متزامنة؟

غالباً ما يمكن لواجهات برمجة تطبيقات إكمال النصوص إرجاع استجابة عبر نفس الاتصال لأن توليد الرموز (tokens) سريع بما يكفي للبث. أما نماذج توليد الصور، سواء كانت تعتمد على الانتشار (diffusion-based) أو النماذج التراجعية الذاتية (autoregressive)، فهي تستغرق وقتاً أطول عادةً ولديها زمن انتقال أكثر تباياً اعتماداً على الدقة، واختيار النموذج، وعمق قائمة الانتظار. إن إبقاء طلب HTTP متزامن مفتوحاً لعشرات الثواني يعد أمراً هشاً: فمهلات العميل، وحدود خمول موازن التحميل، وانقطاعات شبكة الهاتف المحمول، كلها تزيد من احتمالية فقدان نتيجة مكتملة دفعت بالفعل مقابل توليدها.

النمط القياسي، المستخدم عبر مزودي توليد الصور، هو نموذج المهام: حيث ترسل طلباً وتتلقى معرف مهمة وحالة أولية (عادةً ما تكون شيئاً مثل queued أو processing). بعد ذلك، إما أن تقوم باستطلاع نقطة نهاية الحالة أو تلقي إشعار عبر خطاف الويب عندما تصل المهمة إلى حالة نهائية، وتقوم بجلب روابط الصور النهائية أو البيانات الثنائية في استدعاء منفصل.

توفر TokenLab الوصول إلى نماذج صور متعددة، بما في ذلك عائلة Nano Banana 2, Nano Banana Pro, and Nano Banana 2 Lite، وGPT Image 2، وReve 2.0، وMAI-Image-2.5، من خلال واجهة API واحدة. راجع دليل نماذج الصور للحصول على القائمة الحالية ودليل مهام توليد الصور غير المتزامنة لمعرفة سلوك نقطة نهاية المهمة الخاص بـ TokenLab. ينطبق النمط العام أدناه بغض النظر عن النموذج الأساسي الذي تستدعيه، ولكن أسماء الحقول الدقيقة وقيم الحالة موثقة في docs.tokenlab.sh ويجب التحقق منها هناك بدلاً من افتراضها من هذه المقالة.

دورة حياة المهمة: الإرسال، الاستطلاع، الاسترداد

على المستوى المفاهيمي، تمر مهمة الصورة غير المتزامنة بثلاث مراحل:

1. الإرسال (Submit): إرسال طلب POST يحتوي على المطالبة (prompt) والمعلمات، واستلام معرف مهمة وحالة أولية.
2. التحقق من الحالة (Check status): إما استطلاع نقطة نهاية GET باستخدام معرف المهمة، أو انتظار حدث خطاف الويب.
3. استرداد المخرجات (Retrieve output): بمجرد وصول الحالة إلى النهاية (نجاح أو فشل)، يتم جلب رابط (روابط) الصورة أو تفاصيل الخطأ.

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

import time
import requests

API_BASE = "https://api.tokenlab.sh/v1"  # تحقق من رابط القاعدة الحالي في docs.tokenlab.sh
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

def submit_image_job(prompt, model="nano-banana-2"):
    resp = requests.post(
        f"{API_BASE}/images/jobs",
        headers=HEADERS,
        json={"prompt": prompt, "model": model, "idempotency_key": generate_key()},
    )
    resp.raise_for_status()
    return resp.json()["job_id"]

def poll_job(job_id, max_wait_seconds=120, interval=2, backoff=1.5):
    waited = 0
    while waited < max_wait_seconds:
        resp = requests.get(f"{API_BASE}/images/jobs/{job_id}", headers=HEADERS)
        resp.raise_for_status()
        data = resp.json()
        if data["status"] in ("succeeded", "failed"):
            return data
        time.sleep(interval)
        waited += interval
        interval = min(interval * backoff, 15)
    raise TimeoutError(f"Job {job_id} did not complete within {max_wait_seconds}s")

job_id = submit_image_job("a studio product shot on white background")
result = poll_job(job_id)
if result["status"] == "succeeded":
    image_url = result["output"]["url"]
else:
    print("job failed:", result.get("error"))

يعد مفتاح التكرار (idempotency_key) في استدعاء الإرسال مهماً: إذا حدث خطأ في الشبكة بعد إنشاء المهمة ولكن قبل أن يتلقى عميلك معرف المهمة، فإن إعادة محاولة استدعاء الإرسال بنفس المفتاح يجب أن تعيد المهمة الموجودة بدلاً من إنشاء عملية توليد مكررة. تأكد مما إذا كانت نقطة نهاية المهمة في TokenLab تدعم مفاتيح التكرار وكيفية ذلك في الوثائق الحالية، حيث أن هذا نمط شائع ولكنه ليس عالمياً عبر جميع المزودين.

الاستطلاع مقابل خطافات الويب: المقايضات

كلا النهجين صالحان؛ ويعتمد الاختيار الصحيح على نمط حركة المرور والبنية التحتية الخاصة بك.

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

خطافات الويب (Webhooks) تدفع إشعاراً إلى خادمك عندما تتغير حالة المهمة، مما يقلل من زمن الانتقال ويقلل من استدعاءات التحقق من الحالة المهدرة. التكلفة تشغيلية: تحتاج إلى نقطة نهاية HTTPS يمكن الوصول إليها علنياً، والتحقق من التوقيع للتأكد من أن الحمولة جاءت بالفعل من المزود، ومعالجة عمليات التسليم المكررة أو غير المرتبة.

توثق مراجع أحداث خطافات الويب الخاصة بـ OpenAI الشكل العام لهذا النمط للعمليات غير المتزامنة: تتلقى نقطة النهاية الخاصة بك حدثاً بنوع ومعرف كائن، والممارسة الموصى بها هي التعامل مع حمولة خطاف الويب كإشعار للذهاب لجلب الحالة الحالية للمورد عبر API، بدلاً من الوثوق بجسم خطاف الويب كمصدر نهائي للحقيقة. نمط "السحب بعد الدفع" (pull-after-push) هذا يستحق الاعتماد بغض النظر عن مزود الصور الذي تتكامل معه، لأنه يحميك إذا تم اقتطاع حمولة خطاف الويب، أو تأخيرها، أو تسليمها أكثر من مرة.

تنفيذ خطافات الويب بأمان

إذا اخترت خطافات الويب لإكمال مهام الصور، فإن الممارسات التالية تقلل من احتمالية الفشل الصامت:

• تحقق من التوقيع في كل طلب خطاف ويب وارد قبل معالجته. ارفض أي شيء لا يتطابق، وقم بتسجيل الرفض بشكل منفصل عن حركة المرور العادية حتى تتمكن من اكتشاف السر المهيأ بشكل خاطئ بسرعة.
• استجب بسرعة، وعالج لاحقاً. أقر بخطاف الويب بحالة 200 بمجرد التحقق منه، ثم سلم العمل الفعلي (جلب الصورة، الكتابة إلى التخزين، إخطار المستخدم) إلى مهمة خلفية أو قائمة انتظار. يعيد المزودون عادةً محاولة تسليم خطاف الويب إذا لم يتلقوا استجابة 2xx في الوقت المناسب، مما قد يسبب معالجة مكررة إذا كان المعالج الخاص بك بطيئاً ومتزامناً.
• إلغاء التكرار حسب معرف المهمة. قم بتخزين معرفات المهام المعالجة (أو تجزئة للحدث) حتى لا يؤدي التسليم المعاد إلى إعادة إنشاء إشعار أو إعادة معالجة كتابة ملف.
• أعد جلب المورد باستخدام معرف المهمة من حمولة خطاف الويب بدلاً من الوثوق بروابط المخرجات المضمنة كنهائية بالضرورة، بما يتوافق مع نمط "السحب بعد الدفع" الموصوف أعلاه.

رسم تخطيطي لمعالج بسيط:

from flask import Flask, request, abort

app = Flask(__name__)
processed_job_ids = set()  # استخدم مخزناً حقيقياً في بيئة الإنتاج

@app.route("/webhooks/image-jobs", methods=["POST"])
def handle_webhook():
    if not verify_signature(request):
        abort(401)

    event = request.get_json()
    job_id = event.get("job_id") or event.get("data", {}).get("id")
    if job_id in processed_job_ids:
        return "", 200  # تمت المعالجة بالفعل، أقر بذلك وتخطَّ

    enqueue_background_task("fetch_and_store_image", job_id)
    processed_job_ids.add(job_id)
    return "", 200

تحقق من أسماء أحداث خطاف الويب الدقيقة، وهيكل الحمولة، ورأس التوقيع المستخدم لإكمال مهام الصور مقابل وثائق المزود الحالية، وبشكل منفصل، مقابل دعم خطاف الويب الخاص بـ TokenLab كما هو موضح في docs.tokenlab.sh، حيث أن هذه التفاصيل خاصة بالمزود ويمكن أن تتغير.

تصميم إعادة المحاولة: ثلاث فئات للفشل

تفشل مهام الصور غير المتزامنة بثلاث طرق متميزة، ويحتاج كل منها إلى معالجة خاصة:

1. فشل الإرسال: إرجاع طلب POST لإنشاء مهمة رمز خطأ 4xx أو 5xx. بالنسبة لأخطاء 5xx وأخطاء الشبكة، أعد المحاولة مع التراجع الأسي (exponential backoff) والارتعاش (jitter)، مع إعادة استخدام نفس مفتاح التكرار حتى لا تنشئ مهام مكررة. بالنسبة لأخطاء 4xx (مطالبة سيئة، نموذج غير صالح، تجاوز الحصة)، فإن إعادة المحاولة دون تغيير الطلب ستفشل مرة أخرى؛ بدلاً من ذلك، اعرض الخطأ للمستدعي.
2. المهام العالقة: بقاء المهمة في حالة غير نهائية لفترة تتجاوز وقت التوليد المتوقع. حدد حداً أقصى لانتظار كل نموذج (يختلف وقت التوليد حسب النموذج والدقة) وتعامل مع المهام التي تتجاوزه على أنها فاشلة لأغراض تطبيقك، حتى لو لم يقم المزود بتمييزها رسمياً على أنها فاشلة بعد. سجل هذه المهام بشكل منفصل، لأن ارتفاع معدل المهام العالقة غالباً ما يشير إلى حادث من جانب المزود.
3. فشل تسليم خطافات الويب: كانت نقطة النهاية الخاصة بك معطلة، أو تم إسقاط التسليم، ولم يصل أي حدث على الإطلاق. لهذا السبب يستحق الاحتفاظ بنسخة احتياطية للاستطلاع حتى في تصميم يعتمد على خطافات الويب أولاً: فحص دوري يتحقق من حالة أي مهمة أقدم من بضع دقائق دون حالة نهائية يلتقط المهام التي فشل خطاف الويب الخاص بها في الوصول بصمت.

قائمة التحقق للقرار

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

السيناريو	النهج الموصى به	السبب
حجم منخفض، أداة داخلية، أو برنامج نصي للدفعة	الاستطلاع (Polling)	الأسهل في البناء؛ لا حاجة لنقطة نهاية عامة
ميزة موجهة للمستخدم حيث يهم زمن الانتقال	خطافات الويب مع فحص استطلاع احتياطي	زمن انتقال أقل؛ الفحص الاحتياطي يلتقط عمليات التسليم المفقودة
حجم مهام مرتفع (آلاف/يوم)	خطافات الويب	يتجنب حجم طلبات التحقق من الحالة المفرط
عدم القدرة على كشف نقطة نهاية HTTPS عامة	الاستطلاع (Polling)	تتطلب خطافات الويب مستقبلاً يمكن الوصول إليه
الحاجة إلى منع التكرار الصارم	مفاتيح التكرار عند الإرسال، وإلغاء التكرار حسب معرف المهمة عند الاستلام	يحمي من عمليات الإرسال المعاد محاولتها وتسليمات خطاف الويب المكررة
نماذج صور متعددة في خط أنابيب واحد	توحيد حالة المهمة ومعالجة الأخطاء في طبقتك الخاصة	المزودون الأساسيون (راجع مقارنة نماذج الصور) لا يتشاركون تصنيفات حالة متطابقة

القيود

تصف هذه المقالة نمطاً عاماً لواجهات برمجة تطبيقات مهام الصور غير المتزامنة ولا تؤكد مسارات نقاط النهاية الدقيقة، أو أسماء الحقول، أو قيم المهلة، أو أسماء أحداث خطاف الويب لـ TokenLab أو لأي مزود نموذج أساسي محدد بخلاف ما تم ذكره أعلاه. تختلف مفردات حالة المهمة، ورؤوس إعادة المحاولة (retry-after)، ومخططات توقيع خطاف الويب بين المزودين ويمكن أن تتغير بمرور الوقت؛ تعامل مع الكود في هذه المقالة ككود توضيحي، وليس ككود إنتاج جاهز للنسخ واللصق، وتأكد من أشكال الطلب والاستجابة الحالية في docs.tokenlab.sh قبل الإطلاق. لا تغطي هذه المقالة التسعير، أو حدود المعدل، أو ضمانات الإنتاجية لأي نموذج محدد.

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

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

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

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

إذا كنت تبني ميزة توليد صور وترغب في مقارنة الوصول القائم على المهام عبر نماذج متعددة في API واحد، فراجع دليل نماذج الصور ودليل مهام توليد الصور غير المتزامنة، ثم ابدأ مع وثائق API الخاصة بـ TokenLab لتأكيد تفاصيل نقطة النهاية وخطاف الويب الحالية لبنائك.