الأدلة

البدء السريع

أنشئ مهمة غير متزامنة وتعامل مع الاستطلاع والإكمال والفشل وعمليات الاستدعاء.

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

إنشاء مهمة

اختر نموذجاً ونقطة نهاية من الكتالوج، ثم أرسل المدخلات المطلوبة لنقطة النهاية. يبدأ هذا المثال مهمة Flux 2 لتحويل النص إلى صورة:

SHELL

curl -X POST "https://runapi.ai/api/v1/flux_2/text_to_image" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Idempotency-Key: 8c8ba3c9-0ce0-4bbd-a9a7-bf59ab639286" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2-pro-text-to-image",
    "prompt": "A product photograph on a clean studio background"
  }'

يُرجع طلب غير متزامن مقبول استجابة 202 Accepted مع معرّف مهمة:

JSON

{
  "id": "task_id",
  "status": "processing"
}

احفظ id مع سجل تطبيقك. إنه المعرّف الثابت المستخدم للاستطلاع والدعم ومطابقة عمليات الاستدعاء.

منع إنشاء مهام مكررة

تقبل نقاط النهاية المُنشِئة للمهام ترويسة اختيارية Idempotency-Key تحمل قيمة غير شفافة تصل إلى 512 حرفًا. أنشئ قيمة واحدة لكل مهمة منطقية واحتفظ بها مع الطلب حتى تعرف ما إذا كان قد قُبِل.

إذا تركت مهلة الانتظار أو فشل الاتصال النتيجة مجهولة، أعد تجربة نفس طلب إنشاء المهمة بالضبط مع نفس المفتاح. يُعيد RunAPI المهمة الأصلية بدلاً من إنشاء مهمة ثانية وتحصيل رسومها. إعادة استخدام مفتاح مع طلب إنشاء مهمة مختلف يُعيد 409 Conflict. أنشئ مفتاحاً جديداً لمهمة جديدة متعمدة، ولا تستخدم X-Client-Request-Id كهذا المفتاح.

استرداد طلب متزامن منقطع

تحتفظ الطرف الطرفية المتزامنة البطيئة عادةً بالاتصال مفتوحاً وتُرجع nفس الاستجابة النهائية كما كانت من قبل. لا تتطلب تغييرات في الاستطلاع للتكاملات الموجودة.

لميزانية اتصال أقصر بشكل متعمد، أرسل Prefer: wait=N. إذا كانت المهمة لا تزال قيد التشغيل بعد انتهاء تلك الميزانية الصريحة، تُعيد RunAPI 202 Accepted مع id المهمة ذاتها وعنوان URL معتماً Location للاسترداد، وRetry-After لفاصل الاستعلام المقترح. اتبع Location بدقة بدلاً من إنشاء عنوان URL للنتيجة يدوياً. تحتفظ نتيجة المهمة المكتملة بحالة HTTP الطرفية والرؤوس المسموح بها ونوع المحتوى والجسم؛ فكّ ترميز response.body وفقاً لـ response.content_type، الذي لا يكون دائماً JSON.

استطلاع حالة مهمة

أضف معرّف المهمة إلى مسار نقطة النهاية ذاتها:

SHELL

curl "https://runapi.ai/api/v1/flux_2/text_to_image/task_id" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

استمر طالما أن status هو processing. استخدم تأخيراً تصاعدياً محدوداً بين الطلبات بدلاً من الاستطلاع المستمر. تصبح المهمة نهائية عندما تكون حالتها completed أو failed.

معالجة الإكمال

تتضمن استجابة completed معرّف المهمة id والحالة النهائية status وحقول النتائج الخاصة بنقطة النهاية. احتفظ بالنتيجة التي تحتاجها وأوقف الاستطلاع. راجع مرجع API الخاص بنقطة النهاية للاطلاع على الشكل الدقيق للنتيجة بدلاً من افتراض أن كل نقطة نهاية وسائط ترجع الحقول ذاتها.

معالجة الفشل

تتضمن استجابة failed معرّف المهمة id والحالة النهائية status وخطأ error من تأليف RunAPI حين يكون متاحاً. أوقف الاستطلاع، وسجِّل المعرّف والخطأ، وأعد المحاولة فقط حين تُصنِّف تطبيقاتك الفشلَ على أنه عارض. تُنشئ كل إعادة محاولة معرّف مهمة جديداً.

استقبال عملية استدعاء

أضف callback_url عبر HTTPS عام إلى طلب الإنشاء حين تريد من RunAPI إرسال أحداث الاستدعاء الموثقة لتلك نقطة النهاية:

JSON

{
  "model": "flux-2-pro-text-to-image",
  "prompt": "A product photograph on a clean studio background",
  "callback_url": "https://your-domain.com/webhooks/runapi"
}

يتطابق كل استدعاء مع حدث دورة حياة واحد في مرجع API الخاص بنقطة النهاية ويحذف تفاصيل الفوترة الخاصة بالاستطلاع فقط. تتضمن عمليات الاستدعاء الطرفية نفس حقول النتيجة الموجودة في استجابات الاستطلاع الطرفي؛ وترسل بعض نقاط النهاية أيضاً عمليات استدعاء processing موثّقة. أعِد استجابة HTTP ناجحة بسرعة وأبقِ الاستطلاع متاحاً للتسوية عند تأخر التسليم أو عدم توفر معالج الاستدعاء لديك.

اقرأ عمليات الاستدعاء لإنشاء سرّ عملية الاستدعاء والتحقق من التوقيعات ومعالجة عمليات إعادة المحاولة بأمان.