تخطَّ إلى المحتوى
الأدلة
الأدلة

البدء السريع

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

عرض Markdown

يستخدم 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 مع سجل تطبيقك. إنه المعرّف الثابت المستخدم للاستطلاع والدعم ومطابقة عمليات الاستدعاء.

إرسال مدخلات الوسائط

حقول Media Input Field هي حقول الطلب التي تحمل عناوين URL للوسائط: الحقول ذات المستوى الأعلى التي تنتهي أسماؤها بـ _url أو _urls، مثل image_url أو image_urls، والحقل url في كل عنصر من video_list، والحقول element_input_urls وelement_input_video_urls وelement_input_audio_urls في كل عنصر من kling_elements. الحقل callback_url هو نقطة نهاية للتسليم وليس Media Input Field. يمكن أن تكون كل قيمة في Media Input Field عنوان URL عامًا يستخدم HTTPS أو data URI بالصيغة data:<mime>;base64,<data>، بحد أقصى 10 MB لكل data URI. تخزن RunAPI كل data URI بوصفه File Upload مؤقتًا تنتهي صلاحيته بعد ساعة واحدة، وتستخدم هذا الرفع في الـ Task. يعيد data URI الذي يتعذر تخزينه 422 مع رمز الخطأ invalid_media_input.

تقبل نقاط نهاية التعديل في GPT Image عناوين HTTPS فقط في source_image_urls. لإرسال صورة محلية إلى هذه النقاط، أنشئ File Upload أولًا ثم مرّر عنوان URL المُعاد.

للملفات التي يزيد حجمها على 10 MB، أنشئ File Upload أولًا باستخدام POST /api/v1/files ثم مرّر عنوان URL المُعاد. يقبل File Upload بطريقة multipart أو من مصدر URL ملفات يصل حجمها إلى 50 MB. تنتهي صلاحية عناوين File Upload أيضًا بعد ساعة واحدة، لذا أنشئ File Upload جديدًا لكل Task يبدأ بعد هذه المدة.

SHELL 
# For this model, non-PNG/JPEG input may return 409 depending on the selected service.
# If rejected, convert WebP/BMP/TIFF/GIF to PNG/JPEG or select a compatible service.
# Actual MIME determines support, even for a .png URL. Rejection happens before task creation or charging.
# This is not a format limit for every service. Existing Task queries remain available.
curl -X POST "https://runapi.ai/api/v1/seedream/decompose_layers" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model":"seedream-5-pro-layer-decomposition","image_url":"https://cdn.runapi.ai/public/samples/image.png"}'

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

تقبل نقاط النهاية المُنشِئة للمهام ترويسة اختيارية 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 وحقول النتائج الخاصة بنقطة النهاية، وusage.cost كمبلغ float USD لتلك المهمة. احتفظ بالنتيجة التي تحتاجها وأوقف الاستطلاع. راجع مرجع API الخاص بنقطة النهاية للاطلاع على الشكل الدقيق للنتيجة بدلاً من افتراض أن كل نقطة نهاية وسائط ترجع الحقول ذاتها.

أغلفة مهام الإنشاء وprocessing وfailed تحذف usage.

تبقى المهام التي تتطلب تسوية نهائية بناءً على الوسائط في حالة processing حتى تُسجَّل تكلفتها النهائية. لا يُرسَل استدعاء الاكتمال إلا بعد هذه التسوية؛ وتطابق قيمة usage.cost فيه القيمة في الاستعلامات اللاحقة عن المهمة. لا تُعرض البيانات المحاسبية المفقودة على أنها صفر: تبقى المهمة في حالة processing أثناء مطابقة هذه البيانات وتسويتها. وعندما تُؤكَّد تكلفة صفرية، تُعاد على هيئة usage.cost: 0.

معالجة الفشل

تتضمن استجابة 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 الخاص بنقطة النهاية. يشارك استدعاء الإكمال قيمة usage.cost مع استجابة الاستطلاع المكتملة؛ وتحذف استدعاءات الإنشاء والمعالجة والفشل الحقل usage. تتضمن عمليات الاستدعاء الطرفية نفس حقول النتيجة الموجودة في استجابات الاستطلاع الطرفي؛ وترسل بعض نقاط النهاية أيضاً عمليات استدعاء processing موثّقة. أعِد استجابة HTTP ناجحة بسرعة وأبقِ الاستطلاع متاحاً للتسوية عند تأخر التسليم أو عدم توفر معالج الاستدعاء لديك.

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

إنشاء مقاطع فيديو Vidu Q4

استخدم POST /api/v1/vidu/image_to_video مع model: "vidu-q4-image-to-video" وfirst_frame_image_url. استخدم POST /api/v1/vidu/reference_to_video مع model: "vidu-q4-reference-to-video"، وprompt غير الفارغ، و1–15 مرتبة reference_image_urls. استرجع كل مهمة باستخدام GET عند إنشائها المسار متبوعًا بـ /:id. تحتوي المهام المكتملة على مجموعة videos من عناوين URL للنتيجة. يمكنك أيضًا تقديم callback_url للاستكمال الإخطارات.

تقبل كلا نقطتي النهاية العدد الصحيح duration_seconds من 3 إلى 16، افتراضيًا 5، وoutput_resolution من 540p، أو 720p، أو 1080p، أو 2k، أو 4k، الافتراضي 720p. audio هو منطقي JSON، افتراضي true؛ صريحة يعمل false على تعطيل الصوت الذي تم إنشاؤه. تقبل المطالبات ما يصل إلى 20000 الشخصيات. تعد مطالبة تحويل الصورة إلى الفيديو اختيارية والإطار الأول يحدد نسبة العرض إلى الارتفاع الخاصة به. المرجع إلى الفيديو يقبل aspect_ratio من 16:9 أو 9:16 أو 1:1 أو 4:3 أو 3:4، 16:9 الافتراضي، وما يصل إلى 3 reference_audio_urls.

استخدم عناوين URL العامة للوسائط HTTP(S). يجب أن تكون الصور JPG/JPEG أو PNG أو WEBP؛ يجب ألا يزيد حجم صورة الإطار الأول عن 50 ميجابايت. كل مرجع صوتي يجب أن يكون الملف MP3، وطوله من 3 إلى 12 ثانية، ولا يزيد حجمه عن 50 ميجابايت. RunAPI يتحقق من أنواع الحقول وأنظمة URL وأعداد المراجع. الجيل يتحقق الموفر من تنسيق الوسائط البعيدة وحجمها ومدة الصوت بشكل غير متزامن. يمكن أن تتسبب الوسائط غير الصالحة في فشل المهمة من خلال الفشل العادي وتدفق استرداد.

أسعار الصورة إلى الفيديو. أسعار المراجع إلى الفيديو.