راجع مصادر schema في Rivya API v1، وقواعد التوافق، والحقول العامة، وعقد OpenAPI JSON للقراءة فقط.

تعرض Rivya API v1 عقد schema للقراءة فقط على:

https://rivya.ai/api/v1/openapi.json

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

مصادر العقد

يشتق العقد من:

schemas طلبات API العامة
رموز الأخطاء العامة
طبقة مرجع نماذج API العامة
كتالوج النماذج نفسه المستخدم في /api/v1/models

قائمة النماذج ديناميكية. لا تبن تكاملات تعتمد على عدد نماذج مكتوب يدويا.

سياسة الإصدارات

إصدار API الحالي هو v1.

قد تشمل التغييرات المتوافقة مع الإصدارات السابقة:

إضافة نموذج إلى /api/v1/models
إضافة حقل استجابة اختياري
إضافة معامل طلب اختياري لنموذج
إضافة رمز خطأ عام جديد

تتطلب التغييرات الكاسرة إصدارا جديدا أو مسار هجرة موثقا.

حدود الحقول العامة

تستخدم حقول schema العامة أسماء عامة:

id
status
model
session_id
message
usage
reserved_credits
final_credits
created_at
updated_at
result
error

لا تعتمد على حقول تخزين المهام الداخلية. فهي ليست جزءا من العقد العام.

Schema الطلب

يقبل POST /api/v1/generations:

model: معرف نموذج عام مطلوب
prompt: سلسلة اختيارية، مطلوبة في كثير من النماذج
params: كائن اختياري بمعاملات خاصة بالنموذج
client_request_id: سلسلة اختيارية لمعرف التتبع الخاص بك

استخدم مرجع Model API من أجل params الخاصة بكل نموذج.

تنتمي الوسائط المرجعية العائدة من /api/v1/files إلى params.referenceMediaItems. توثق schema الحقول url، وkind، وname الاختياري، وmimeType الاختياري، وdurationSeconds الاختياري، وdurationToken الاختياري. لا تقبل Rivya حقل files على المستوى الأعلى في POST /api/v1/generations.

يقبل POST /api/v1/files بيانات multipart form مع file، وkind، وmodel الاختياري، وclient_request_id الاختياري. الاستجابة هي PublicApiFile. يعيد GET /api/v1/files/{fileId} البيانات الوصفية العامة نفسها للملفات التي يملكها حساب API.

يقبل POST /api/v1/chat/completions الحقول model، وmessage، وsession_id الاختياري، وعناصر التحكم الاختيارية، ومرفقات file_id الاختيارية من Files API، وclient_request_id الاختياري. ويعيد رسالة مساعد كاملة غير متدفقة.

يقبل POST /api/v1/chat/completions/stream schema الطلب نفسها ويعيد text/event-stream مع أحداث session.created، وmessage.delta، وmessage.completed، وusage.completed، وheartbeat، وerror، وdone. لا يقبل Chat API v1 مصفوفة messages خام.

Schemas الاستجابة

يوثق مخرج OpenAPI أشكال الاستجابة العامة التالية:

ModelList لـ GET /api/v1/models
PublicApiModel وModelParam لاختيار النماذج ونماذج المعاملات
PublicApiFile لـ POST /api/v1/files وGET /api/v1/files/{fileId}
ReferenceMediaItem لمعاملات التوليد المدعومة بالملفات
PublicGeneration لاستجابات الإنشاء والحالة
GenerationResult وGenerationError للمهام المكتملة
ChatCompletionRequest، وChatCompletion، وChatSession، وChatMessage، وChatUsage، وChatCredits، وschemas أحداث بث Chat API
CreditBalance لـ GET /api/v1/credits
WebhookEndpoint، وWebhookEvent، وWebhookDelivery، وWebhookTestResult من أجل API webhooks الموقعة
PublicApiError لاستجابات الأخطاء المستقرة

schema آمنة للاستخدام في تحقق العميل واختبارات التكامل الداخلية. يظل TypeScript SDK beta مقيدا بهذه schema.

حوكمة الأمثلة

تستخدم أمثلة curl وJavaScript وPython في هذه الوثائق أسماء الحقول العامة نفسها الموجودة في schema:

Authorization: Bearer rvya_sk_...
Idempotency-Key
model
prompt
message
session_id
params
client_request_id

تستخدم أمثلة Chat أيضا:

chat:create
chat:read
file_id

تستخدم أمثلة Webhook أيضا:

Rivya-Webhook-Signature
Rivya-Webhook-Timestamp
webhooks:manage

عندما يتغير معامل نموذج، حدّث كتالوج النماذج وpublic serializer أولا. يجب أن تستهلك الوثائق والمصحح تلك الطبقة العامة نفسها بدلا من نسخ جدول منفصل.

عقد OpenAPI وSchema