Rivya API هو مسار المطورين لاستخدام قدرات نماذج Rivya من داخل منتجك، أو سكربتك، أو سير عملك.
إنه ليس منتجا منفصلا عن Rivya Studio. يستخدم حدود الحساب نفسها، ومحفظة الرصيد نفسها، وطبقة النماذج العامة نفسها التي يراها المستخدمون عبر Rivya. الفرق هو طريقة بدء العمل: بدلا من النقر داخل Studio، يرسل تطبيقك الطلبات باستخدام مفتاح API.
إذا كنت تحتاج تفاصيل نقطة النهاية، فابدأ بـ نظرة عامة على Rivya API ودليل البدء السريع لـ Rivya API. هذا المقال هو الشرح على مستوى المنتج: ما الغرض من API، وأين يناسب، ومتى لا يجب أن يكون المسار الأول.
النسخة المختصرة
يتيح Rivya API v1 لحساب مسجل الدخول إنشاء مفاتيح API واستدعاء قدرات نماذج Rivya من خارج واجهة الويب.
يشمل سطح API الحالي:
- اكتشاف النماذج عبر قائمة نماذج API
- مهام توليد غير متزامنة للصور والفيديو والصوت
- رفع Files API للنماذج التي تحتاج وسائط مرجعية
- استعلام دوري لحالة التوليد باستخدام معرفات المهام العامة
- فحوص رصيد الحساب
- دورات Chat API، بما في ذلك تدفق SSE اختياري
- ويبهوكات موقعة لاكتمال التوليد
- إصدار تجريبي من TypeScript SDK للفرق التي تريد غلاف عميل
مركز المطورين العام هو Developers. إنه أفضل مدخل إذا أردت نظرة موجهة، وروابط إلى إعدادات مفاتيح API، وتدفق تصحيح آمن.
لماذا لدى Rivya واجهة API
Studio مفيد عندما ما زال شخص يختار النماذج، ويشكل المطالبات، ويراجع المخرجات، ويقرر ما يجب فعله بعد ذلك.
API مفيد عندما يتحول ذلك القرار إلى سير عمل منتج أو عملية قابلة للتكرار.
أمثلة شائعة:
- يريد منتج توليد تنويعات صور بعد أن يرسل مستخدم موجزا
- يحتاج سير عمل تسويقي إلى إنشاء مسودات بصرية من مدخلات حملة منظمة
- تحتاج أداة داخلية إلى إرسال مهام فيديو أو صوت دون أن يفتح أحد المتصفح
- يريد نظام دعم أو محتوى دورة نموذج محادثة داخل واجهته الخاصة
- تريد خدمة خلفية ردود نداء موقعة عندما تنتهي مهام التوليد
في هذه الحالات، يبقي Rivya API العمل متصلا بحساب Rivya نفسه بدلا من فرض حزمة منفصلة للفوترة، واختيار النموذج، وحالة المهمة.
ما الذي لا يستبدله API
لا يستبدل API كل سبب لاستخدام Rivya مباشرة.
استخدم Studio أو أسطح العمل العامة عندما:
- ما زالت المطالبة تحتاج إلى استكشاف بشري
- اختيار النموذج غير مستقر
- يحتاج منشئ إلى مقارنة المخرجات بصريا
- يعتمد المشروع على السجل المحفوظ والمراجعة اليدوية
- لم يقرر الفريق بعد أي صيغة إدخال وإخراج يجب أن تصبح قابلة للتكرار
استخدم API عندما يكون سير العمل واضحا بما يكفي للأتمتة.
هذا الحد مهم. السؤال الإبداعي الغامض ينتمي عادة إلى Studio أولا. أما تدفق المنتج المعروف بمدخلات متوقعة فيمكن نقله إلى API.
اللبنات الرئيسية
فكر في API كست قطع متصلة.
| اللبنة | ما الذي تعالجه | أين تقرأ بعد ذلك |
|---|---|---|
| مفاتيح API | وصول من خادم إلى خادم من حسابك | مصادقة API |
| النماذج | معرفات النماذج العامة ومعلومات الجاهزية | نماذج API |
| عمليات التوليد | مهام صور وفيديو وصوت غير متزامنة | إنشاء عملية توليد |
| الملفات | رفع صور أو فيديو أو صوت مرجعي | Files API |
| المحادثة | دورات محادثة غير متدفقة أو متدفقة | Chat API |
| Webhooks | أحداث اكتمال موقعة لمهام التوليد | API Webhooks |
وثائق API هي المصدر لشكل الطلب والاستجابة. يجب أن يساعدك هذا المقال على تحديد القطعة التي تحتاجها أولا.
كيف يعمل الرصيد
يسحب استخدام API من محفظة رصيد حساب Rivya نفسها التي يستخدمها Studio.
يعني ذلك أن API ليس وكيلا مجهولا للنماذج. الطلب ينتمي إلى حساب Rivya، ويستخدم مفتاح API أنشأه ذلك الحساب، ويتبع حد الرصيد على مستوى المنتج كما هو موضح في رصيد API.
هذا مفيد للفرق لأن تجارب Studio واستخدام API يبقيان ضمن نموذج تشغيلي واحد. يمكنك اختبار نموذج يدويا، ثم نقل الجزء القابل للتكرار إلى تكامل دون إنشاء طبقة فوترة ثانية.
كيف تدخل الملفات في الصورة
يمكن لبعض النماذج العمل من النص وحده. وتحتاج نماذج أخرى إلى صورة أو فيديو أو ملف صوت مرجعي.
في تكاملات API، يجب أن تمر تلك المراجع عبر Files API. ينشئ الرفع سجل ملف مدار يمكن تمريره إلى معاملات النماذج المدعومة.
القاعدة العملية بسيطة:
- إذا كان النموذج يقبل إدخال نص فقط، فابدأ من نقطة نهاية التوليد
- إذا كان النموذج يحتاج وسائط مرجعية، فارفع الملف أولا
- إذا كان النموذج نموذج محادثة مع مرفقات صور، فاستخدم Chat API ومعرفات الملفات
لا تصمم تكاملك حول تدفقات رفع خاصة بالمتصفح فقط أو جلسات Studio محفوظة. لدى API حد ملفات عام خاص به لسبب واضح.
أين تساعد Webhooks
الاستعلام الدوري هو أسهل مسار تكامل أول. أرسل مهمة توليد، واحفظ معرف المهمة العام، ثم استعلم دوريا حتى تنجح أو تفشل.
تصبح Webhooks مفيدة عندما يصبح التكامل أقرب إلى الإنتاج:
- لا تريد عاملا يجري استعلاما دوريا لكل مهمة
- يحتاج تطبيقك إلى تحديث سجل عند انتهاء التوليد
- تريد حدثا موقّعا يمكن إعادة محاولته بأمان
- تحتاج المهام الفاشلة إلى الانتقال إلى مسار استرداد واضح
لعقد الحدث الموقع، استخدم API Webhooks. أبق مستقبل الويبهوك ضيقا: تحقق من التوقيعات، وتعامل مع الأحداث المكررة، وتجنب وضع قيم سرية في السجلات.
مشروع API أول جيد
أفضل مشروع API أول يكون عادة صغيرا وملموسا.
مثلا:
- أنشئ مفتاح API في الإعدادات
- استدع قائمة النماذج
- اختر نموذجا متاحا واحدا
- أرسل مهمة توليد واحدة باستخدام مفتاح عدم التكرار
- أجر استعلاما دوريا لنقطة نهاية الحالة
- افحص الرصيد قبل وبعد
- عندها فقط أضف Files API أو Chat API أو Webhooks
يعطيك هذا المسار تكاملا عاملا دون خلط كل ميزات API في الاختبار الأول.
متى يكون API نقطة بداية خاطئة
غالبا لا يكون API الخطوة الأولى الصحيحة عندما:
- لم يختر الفريق عائلة نماذج بعد
- الناتج المطلوب ما زال يتغير في كل تشغيل
- تعتمد المطالبة على الذوق والمراجعة اليدوية
- سيخفي التكامل استخدام الرصيد عن الأشخاص الذين يحتاجون إلى فهمه
- يحتاج المنتج إلى عرض تجريبي عام قبل أن يحتاج إلى الأتمتة
في هذه الحالات، ابدأ من Image، أو Video، أو Audio، أو Chat، أو AI Models. عندما يصبح المسار قابلا للتكرار، انقل الجزء المستقر إلى API.
إلى أين تذهب بعد ذلك
- افتح Developers لمركز API العام ومصحح الأخطاء.
- اقرأ دليل البدء السريع لـ Rivya API لإجراء أول طلب آمن.
- اقرأ مصادقة API قبل وضع مفتاح على خادم.
- اقرأ نماذج API قبل اختيار معرفات النماذج.
- اقرأ متى تستخدم Rivya API بدلا من Studio إذا كان حد المنتج ما زال غير واضح.
- اقرأ كيف تبني سير عمل AI متعدد الوسائط باستخدام Rivya API عندما تخطط لتكامل كامل للصور، أو الفيديو، أو الصوت، أو المحادثة.
