Rivya API v1 کے اسکیما ذرائع، مطابقت کے اصول، عوامی خانوں اور صرف پڑھنے کے قابل OpenAPI JSON معاہدے کا جائزہ لیں۔

Rivya API v1 یہاں صرف پڑھنے کے لیے اسکیما معاہدہ فراہم کرتا ہے:

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

یہ راستہ عوامی معاہدے کا نتیجہ فراہم کرتا ہے۔ یہ صارف کے سیشن کا ڈیٹا نہیں پڑھتا، ماڈل کے کام جمع نہیں کرتا اور کریڈٹ استعمال نہیں کرتا۔

معاہدے کے ماخذ

معاہدہ ان ماخذوں سے اخذ ہوتا ہے:

عوامی API درخواست کے اسکیما
عوامی خرابی کے کوڈ
عوامی API ماڈل حوالہ تہہ
وہی ماڈل فہرست جو مصنوعات استعمال کرتی ہیں

ماڈلز کی فہرست متحرک ہے۔ ایسا انضمام نہ بنائیں جو ہاتھ سے لکھی ہوئی ماڈلز کی تعداد پر منحصر ہو۔

نسخے کی پالیسی

موجودہ API نسخہ 1.0.0 ہے۔

پچھلے نسخوں سے مطابقت رکھنے والی تبدیلیوں میں یہ شامل ہو سکتے ہیں:

/api/v1/models میں ماڈل شامل کرنا
جواب میں اختیاری خانہ شامل کرنا
کسی ماڈل کے لیے اختیاری درخواستی پیرامیٹر شامل کرنا
نیا عوامی خرابی کوڈ شامل کرنا

عدم مطابقت پیدا کرنے والی تبدیلیوں کے لیے نیا نسخہ یا دستاویزی منتقلی کا راستہ درکار ہے۔

عوامی خانوں کی حد

عوامی اسکیما کے خانے عوامی نام استعمال کرتے ہیں:

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

کام کے اندرونی ذخیرے کے خانوں پر انحصار نہ کریں۔ وہ عوامی معاہدے کا حصہ نہیں ہیں۔

درخواست کا خاکہ

POST /api/v1/generations یہ چیزیں قبول کرتا ہے:

model: لازمی عوامی ماڈل شناخت
prompt: اختیاری عبارت، مگر بہت سے ماڈلز کے لیے لازمی
params: ماڈل کے مخصوص پیرامیٹرز پر مشتمل اختیاری آبجیکٹ
client_request_id: آپ کی اپنی سراغ رساں شناخت کے لیے اختیاری عبارت

ماڈل کے مخصوص params کے لیے ماڈل API حوالہ استعمال کریں۔

/api/v1/files سے ملنے والے حوالہ جاتی میڈیا کو params.referenceMediaItems کے اندر رکھنا چاہیے۔ اسکیما 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 POST /api/v1/generations میں بالائی سطح کا files خانہ قبول نہیں کرتا۔

POST /api/v1/files متعدد حصوں پر مشتمل فارم ڈیٹا قبول کرتا ہے، جس میں 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، اختیاری کنٹرولز، اختیاری Files API file_id منسلکات اور اختیاری client_request_id قبول کرتا ہے۔ یہ معاون کا ایک مکمل، غیر رواں پیغام واپس کرتا ہے۔

POST /api/v1/chat/completions/stream وہی درخواستی اسکیما قبول کرتا ہے اور text/event-stream واپس کرتا ہے، جس میں session.created، message.delta، message.completed، usage.completed، heartbeat، error اور done واقعات شامل ہوتے ہیں۔ Chat API v1 خام messages سلسلہ قبول نہیں کرتا۔

جواب کے خاکے

OpenAPI نتیجہ ان عوامی جوابی ساختوں کی وضاحت کرتا ہے:

GET /api/v1/models کے لیے ModelList
ماڈل کے انتخاب اور پیرامیٹر فارم کے لیے PublicApiModel اور ModelParam
POST /api/v1/files اور GET /api/v1/files/{fileId} کے لیے PublicApiFile
فائل پر مبنی نتیجہ سازی کے پیرامیٹرز کے لیے ReferenceMediaItem
تخلیق اور حالت کے جوابات کے لیے PublicGeneration
مکمل کاموں کے لیے GenerationResult اور GenerationError
Chat API کے لیے ChatCompletionRequest، ChatCompletion، ChatSession، ChatMessage، ChatUsage، ChatCredits اور رواں چیٹ واقعات کے اسکیما
GET /api/v1/credits کے لیے CreditBalance
دستخط شدہ API ویب ہکس کے لیے WebhookEndpoint، WebhookEvent، WebhookDelivery اور WebhookTestResult
مستقل خرابی جوابات کے لیے PublicApiError

یہ اسکیما کلائنٹ کی توثیق اور اندرونی انضمامی آزمائشوں کے لیے محفوظ ہے۔ TypeScript SDK کا آزمائشی نسخہ اسی اسکیما کی حدود میں رہتا ہے۔

مثالوں کی نگرانی

ان دستاویزات میں curl، JavaScript اور Python کی مثالیں اسکیما جیسے عوامی خانوں کے نام استعمال کرتی ہیں:

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

چیٹ کی مثالیں مزید یہ استعمال کرتی ہیں:

chat:create
chat:read
file_id

ویب ہک کی مثالیں مزید یہ استعمال کرتی ہیں:

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

جب ماڈل کا پیرامیٹر بدلے تو پہلے ماڈل فہرست اور عوامی سلسلہ ساز کو تازہ کریں۔ دستاویزات اور نقص تلاش کرنے والے آلے کو الگ جدول کی نقل بنانے کے بجائے اسی عوامی تہہ سے معلومات لینی چاہییں۔

OpenAPI اور اسکیما کا معاہدہ