Rivya API v1 के स्कीमा स्रोत, अनुकूलता नियम, सार्वजनिक फ़ील्ड और केवल-पढ़ने योग्य OpenAPI JSON अनुबंध की समीक्षा करें।

Rivya API v1 यहां केवल-पढ़ने योग्य स्कीमा अनुबंध उपलब्ध कराता है:

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

यह मार्ग सार्वजनिक अनुबंध का आउटपुट है। यह उपयोगकर्ता सत्र का डेटा नहीं पढ़ता, मॉडल कार्य नहीं भेजता और खाते का निजी डेटा उजागर नहीं करता।

अनुबंध के स्रोत

अनुबंध इन स्रोतों से बनता है:

सार्वजनिक API अनुरोध की संरचनाएं
सार्वजनिक त्रुटि कोड
सार्वजनिक API मॉडल संदर्भ परत
वही मॉडल सूची जिसे /api/v1/models इस्तेमाल करता है

मॉडल सूची बदलती रहती है। ऐसे एकीकरण न बनाएं जो हाथ से लिखी गई मॉडल संख्या पर निर्भर हों।

संस्करण नीति

मौजूदा API संस्करण v1 है।

पिछले संस्करणों के अनुकूल बदलावों में ये शामिल हो सकते हैं:

/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: जरूरी सार्वजनिक मॉडल ID
prompt: वैकल्पिक स्ट्रिंग, कई मॉडल में जरूरी
params: मॉडल-विशिष्ट मापदंडों वाला वैकल्पिक ऑब्जेक्ट
client_request_id: आपकी अपनी अनुरेखण 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 ऊपरी स्तर का files फ़ील्ड POST /api/v1/generations में स्वीकार नहीं करता।

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 और स्कीमा अनुबंध