راجع مصادر 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 الاختياريين، وwidth / height / sizeBytes / imageDimensionsToken الاختيارية، وframesPerSecond / videoBitrateMbps / videoMetadataToken الاختيارية. تتطلب كل صورة مرجعية لنماذج Image5 أو لنموذجي Grok Imagine Image 2.0 وWan 3.0 رمز الصورة الموقع وحجم البايتات المرتبط من استجابة الرفع الأصلية المرتبطة بالنموذج؛ ويفرض Layer Decomposition أيضا الحدود الهندسية الموثقة له. ويتطلب كل فيديو مرجعي لنماذج Video8 أو Wan 3.0 رمز المدة الموقع والبيانات الوصفية الموقعة للفيديو من استجابة الرفع الأصلية المرتبطة بالنموذج. لا تقبل Rivya حقل files على المستوى الأعلى في POST /api/v1/generations.

يقبل POST /api/v1/files بيانات multipart form مع file، وkind، وmodel الاختياري، وclient_request_id الاختياري. الاستجابة هي PublicApiFile، وتشمل size_bytes وأبعاد الصورة القابلة لأن تكون فارغة وimage_dimensions_token، والحقول القابلة لأن تكون فارغة video_width وvideo_height وframes_per_second وvideo_bitrate_mbps وvideo_file_size_bytes وvideo_metadata_token. يعيد GET /api/v1/files/{fileId} البيانات الوصفية العامة للملفات التي يملكها حساب API، لكن رمز البيانات الوصفية الموقع الذي لم يُحفظ قد يعود بقيمة null ويجب استبداله بإعادة الرفع.

يرتبط video_metadata_token بحساب API، والنموذج المستهدف، وعنوان URL، ونوع MIME، والأبعاد، ومعدل الإطارات، ومعدل البت، وحجم الرفع بالبايت. ولا يحل محل duration_token؛ يجب أن توفر مراجع فيديو Video8 وWan 3.0 التي تستخدم العقدين كلا الرمزين. وتربط رموز مدة الصوت في Wan 3.0 أيضا نوع MIME وحجم الرفع بالبايت.

بالنسبة إلى wan-3-0-video، لا يقبل params إلا الحقول seedance_scene وvariant وresolution وaspect_ratio وduration وaudio وseed وreferenceMediaItems. تكون مشاهد النص والإطارات والمراجع متبادلة الاستبعاد. قيمة المدة الذكية هي -1، وتحجز 30 ثانية، ولا تصلح مع فيديو مرجعي؛ وتُرفض المفاتيح العشوائية والوسائط غير الموقعة واختصارات تحويل الملف إلى فيديو وتحويل الرابط إلى فيديو دون معالجة بديلة.

يقبل 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