ابن سير عمل متعدد الوسائط باستخدام Rivya API

تكامل Rivya API الجيد ليس مجرد طلب واحد إلى نموذج واحد.

معظم سير العمل الحقيقي في المنتجات يتكون من سلسلة صغيرة: اختر النموذج المناسب، حضر المدخل، ارفع ملفات مرجعية عند الحاجة، أرسل مهمة، راقب الحالة، عالج الأرصدة، ونبه المنتج عندما تصبح النتيجة جاهزة.

تعرض هذه المقالة شكل التخطيط. استخدم Rivya API Quickstart لأقصر مسار قابل للتشغيل، واستخدم وثائق API للحقول الدقيقة في الطلب.

ابدأ بلحظة المنتج

قبل اختيار نقاط النهاية، صف لحظة المنتج في جملة واحدة.

أمثلة:

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

هذه الجملة تمنع التكامل من التحول إلى مجموعة فضفاضة من استدعاءات API.

ارسم سير العمل قبل كتابة الكود

استخدم هذا الجدول قبل فتح مخطط الطلب.

يجب أن يكون سير العمل واضحا بما يكفي ليكون لكل منطقة API سبب للوجود.

الخطوة 1: أنشئ مفتاحا لهذا التكامل

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

تجنب استخدام مفتاح واحد لكل شيء. تسمية المفاتيح بحسب الغرض تجعل المراجعة اللاحقة أسهل:

• production-image-workflow
• staging-video-tests
• internal-chat-assistant
• webhook-smoke-test

اقرأ API Authentication قبل تخزين المفتاح. يظهر السر الكامل مرة واحدة فقط، لذلك يجب أن يحفظه فريقك فورا في مخزن أسرار مناسب من جهة الخادم.

الخطوة 2: اختر النماذج من قائمة API العامة

لا تثبت نموذجا في الكود فقط لأنه نجح في اختبار يدوي.

استخدم API Models وModel API Reference لتأكيد:

• معرف النموذج العام
• هل هو متاح عبر API
• وضع الإدخال المدعوم
• توقعات المطالبة والمعلمات
• هل Files API مطلوب
• سلوك الأرصدة وملاحظات الجاهزية

هنا تصبح كثير من التكاملات أنظف. قد يكون النموذج مثاليا لاختبار Studio يدوي، لكنه ليس بالضرورة النموذج الأول الصحيح لتدفق منتج مؤتمت.

الخطوة 3: قرر هل تكون Files API جزءا من النسخة الأولى

إذا كان النموذج يستطيع العمل من إدخال نصي، فأبق النسخة الأولى نصية فقط.

أضف Files API فقط عندما يحتاج سير العمل فعلا إلى وسائط مرجعية.

عندما تحتاجه، عرف:

• أنواع الملفات التي يقبلها المنتج
• من يملك خطوة تنظيف الملفات
• ماذا يحدث عند فشل الرفع
• كيف تمرر بيانات الملف المرتجعة إلى معلمات النموذج
• هل يجب إعادة استخدام الملف نفسه أم رفعه مرة أخرى

هذا يمنع إخفاء تجربة ملفات هشة خلف زر توليد يبدو نظيفا.

الخطوة 4: أرسل مهمة توليد واحدة

لتوليد الصور والفيديو والصوت، النمط المعتاد هو:

1. حضر معرف النموذج، والمطالبة، والمعلمات المدعومة
2. أضف مفتاح عدم التكرار لإعادة المحاولة بأمان
3. أرسل عبر نقطة نهاية التوليد
4. احفظ معرف المهمة العام
5. استعلم عن الحالة حتى تصل المهمة إلى حالة نهائية

استخدم Create Generation لشكل الطلب وGeneration Status لمعالجة النتائج.

يجب أن يعامل المنتج حالات queued وprocessing وsucceeded وfailed كحالات مفهومة للمستخدم. لا تجعل المستخدمين يقرؤون تفاصيل النظام أو يخمنون لماذا تكون المهمة بطيئة.

الخطوة 5: استخدم Chat API لنماذج المحادثة

يجب أن تستخدم نماذج المحادثة Chat API، لا نقطة نهاية التوليد.

هذا مهم لأن عمل المحادثة له سلوك مختلف:

• يمكن أن تنتمي جولات المحادثة إلى جلسات أنشأها API
• التجربة غير المتدفقة وتجربة بث SSE مختلفتان للمستخدم
• تستخدم مرفقات الصور معرفات ملفات من Files API
• تسوية الأرصدة تتبع جولة المحادثة بدلا من مهمة وسائط غير متزامنة عادية

إذا كان منتجك يحتاج إلى إجابة مساعد داخل واجهته الخاصة، فقد يكون Chat API هو المسار الصحيح. وإذا كان المستخدم ما زال يستكشف الأفكار، فقد يكون Rivya Chat أو Studio أفضل.

الخطوة 6: ابدأ بالاستعلام، ثم أضف Webhooks

في النسخة الأولى، يكون الاستعلام الدوري أسهل في الفهم.

أضف API Webhooks عندما:

• يكون لدى المنتج كثير من المهام غير المتزامنة
• لا ينبغي للعملاء المنتظرين أن يستعلموا مباشرة
• تحتاج الأنظمة اللاحقة إلى أحداث اكتمال موقعة
• يكون تصميم إعادة المحاولة والتعامل مع التكرارات جاهزا

يجب أن يكون مستقبل الويبهوك بسيطا وصارما: تحقق من التوقيع، واقبل الأحداث الآمنة عند التكرار، وحدث سجل منتج واحدا، وسجل فقط ما يمكن تسجيله بأمان.

الخطوة 7: اجعل الأرصدة مرئية في المنتج

يستخدم Rivya API أرصدة الحساب نفسها التي يستخدمها Studio.

يجب أن يقرر تكاملك مقدار ما سيعرضه من ذلك. على الأقل، يجب أن يعرف الفريق:

• أي حساب يملك مفتاح API
• أي سير عمل يمكن أن يستهلك الأرصدة
• ماذا يحدث عندما تكون الأرصدة منخفضة جدا
• كيف تشرح حالات فشل التوليد
• أين ترسل شخصا لأسئلة الأرصدة والفوترة

استخدم API Credits، وCredits & Billing in Rivya، وHow to Think About Rivya Credits, Packs, and Plans لنموذج المحفظة المرئي للمستخدم.

نسخة أولى صغيرة

النسخة الأولى الجيدة تكون محدودة عمدا.

مثلا:

1. مفتاح API واحد
2. نموذج صورة واحد محدد
3. لا رفع ملفات بعد
4. طلب توليد واحد
5. مسار استعلام دوري واحد للحالة
6. معاينة نتيجة بسيطة واحدة داخل منتجك
7. رسالة خطأ أرصدة واضحة واحدة

هذه النسخة تثبت الاتصال قبل إضافة مزيد من الأجزاء المتحركة.

نسخة أكثر اكتمالا

بعد أن تعمل النسخة الأولى، يمكن لسير عمل أكمل أن يضيف:

• Files API للصور أو الفيديوهات المرجعية
• عناصر تحكم خاصة بمعلمات النموذج
• عدم التكرار مرتبطا بسجل منتجك
• Webhooks موقعة للاكتمال
• Chat API لجولات المساعد
• تدفق أحداث من الخادم عندما تحتاج المحادثة إلى إخراج حي
• عروض إدارية أو دعم للمهام الفاشلة

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

أخطاء التكامل الشائعة

تجنب هذه الأنماط:

• البدء بكل ميزات API في وقت واحد
• إخفاء استخدام الأرصدة عن مالك الحساب
• استخدام افتراضات خاصة بـ Studio داخل تدفق API
• التعامل مع رفع الملفات كفكرة لاحقة
• إعادة محاولة طلبات التوليد من دون عدم تكرار
• استخدام Chat API لوظائف يجب أن تكون توليدا غير متزامن
• استخدام نقاط نهاية التوليد لجولات المحادثة
• تسجيل مفاتيح API كاملة، أو أسرار الويبهوك، أو تفاصيل ملفات مؤقتة

أكثر سير عمل API أمانا يكون واضحا بشأن الملكية، والحالة، ومعالجة الفشل.

إلى أين تنتقل بعد ذلك

• ابدأ من Developers لمركز API العام.
• استخدم Rivya API Quickstart لتشغيل أول طلب.
• استخدم API Models قبل اختيار model IDs.
• استخدم Files API فقط عندما يحتاج النموذج فعلا إلى وسائط مرجعية.
• استخدم Chat API لجولات المحادثة واستجابات المحادثة المتدفقة.
• استخدم API Webhooks عندما لا يعود الاستعلام الدوري كافيا.
• إذا كان سير العمل لا يزال يحتاج إلى استكشاف بشري، فاقرأ When to Use Rivya API Instead of Studio قبل أتمتته.