Ελέγξτε πηγές schema, κανόνες συμβατότητας, δημόσια πεδία και το read-only OpenAPI JSON συμβόλαιο του Rivya API v1.

Το Rivya API v1 εκθέτει read-only συμβόλαιο schema στη διεύθυνση:

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

Αυτό το route είναι δημόσιο contract output. Δεν διαβάζει δεδομένα session χρήστη, δεν υποβάλλει εργασίες μοντέλων και δεν εκθέτει ιδιωτικά δεδομένα λογαριασμού.

Πηγές συμβολαίου

Το συμβόλαιο προκύπτει από:

δημόσια API request schemas
δημόσιους κωδικούς σφάλματος
το δημόσιο επίπεδο αναφοράς μοντέλων API
τον ίδιο κατάλογο μοντέλων που χρησιμοποιεί το /api/v1/models

Η λίστα μοντέλων είναι δυναμική. Μην χτίζετε ενσωματώσεις που εξαρτώνται από χειροκίνητα γραμμένο πλήθος μοντέλων.

Πολιτική εκδόσεων

Η τρέχουσα έκδοση API είναι v1.

Οι backward-compatible αλλαγές μπορεί να περιλαμβάνουν:

προσθήκη μοντέλου στο /api/v1/models
προσθήκη προαιρετικού πεδίου απόκρισης
προσθήκη προαιρετικής παραμέτρου αιτήματος για μοντέλο
προσθήκη νέου δημόσιου κωδικού σφάλματος

Οι breaking changes απαιτούν νέα έκδοση ή τεκμηριωμένη διαδρομή μετάβασης.

Όριο δημόσιων πεδίων

Τα δημόσια πεδία schema χρησιμοποιούν δημόσια ονόματα:

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

Μην εξαρτάστε από εσωτερικά πεδία αποθήκευσης εργασιών. Δεν αποτελούν μέρος του δημόσιου συμβολαίου.

Request schema

Το POST /api/v1/generations δέχεται:

model: απαιτούμενο δημόσιο model ID
prompt: προαιρετικό string, απαιτείται από πολλά μοντέλα
params: προαιρετικό object με model-specific παραμέτρους
client_request_id: προαιρετικό string για το δικό σας trace ID

Χρησιμοποιήστε την Αναφορά API μοντέλων για model-specific params.

Τα μέσα αναφοράς που επιστρέφει το /api/v1/files ανήκουν μέσα στο params.referenceMediaItems. Το schema τεκμηριώνει url, kind, προαιρετικό name, προαιρετικό mimeType, προαιρετικό durationSeconds και προαιρετικό durationToken. Το Rivya δεν δέχεται top-level πεδίο files στο POST /api/v1/generations.

Το POST /api/v1/files δέχεται multipart form data με file, kind, προαιρετικό model και προαιρετικό client_request_id. Η απόκριση είναι PublicApiFile. Το GET /api/v1/files/{fileId} επιστρέφει τα ίδια δημόσια metadata αρχείου για αρχεία που ανήκουν στον λογαριασμό API.

Το POST /api/v1/chat/completions δέχεται model, message, προαιρετικό session_id, προαιρετικά controls, προαιρετικά συνημμένα Files API file_id και προαιρετικό client_request_id. Επιστρέφει ένα πλήρες non-streaming μήνυμα assistant.

Το POST /api/v1/chat/completions/stream δέχεται το ίδιο request schema και επιστρέφει text/event-stream με events session.created, message.delta, message.completed, usage.completed, heartbeat, error και done. Το Chat API v1 δεν δέχεται raw array messages.

Response schemas

Το OpenAPI output τεκμηριώνει αυτές τις δημόσιες μορφές απόκρισης:

ModelList για GET /api/v1/models
PublicApiModel και ModelParam για επιλογή μοντέλου και φόρμες παραμέτρων
PublicApiFile για POST /api/v1/files και GET /api/v1/files/{fileId}
ReferenceMediaItem για παραμέτρους generation που στηρίζονται σε αρχεία
PublicGeneration για αποκρίσεις δημιουργίας και κατάστασης
GenerationResult και GenerationError για ολοκληρωμένες εργασίες
ChatCompletionRequest, ChatCompletion, ChatSession, ChatMessage, ChatUsage, ChatCredits και Chat stream event schemas για Chat API
CreditBalance για GET /api/v1/credits
WebhookEndpoint, WebhookEvent, WebhookDelivery και WebhookTestResult για υπογεγραμμένα API webhooks
PublicApiError για σταθερές αποκρίσεις σφάλματος

Το schema είναι ασφαλές για χρήση σε client validation και εσωτερικά integration tests. Το beta TypeScript SDK παραμένει περιορισμένο από αυτό το schema.

Διακυβέρνηση παραδειγμάτων

Τα παραδείγματα curl, JavaScript και Python σε αυτά τα docs χρησιμοποιούν τα ίδια δημόσια ονόματα πεδίων με το 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

Όταν αλλάζει μια παράμετρος μοντέλου, ενημερώστε πρώτα τον κατάλογο μοντέλων και τον δημόσιο serializer. Τα docs και ο debugger πρέπει να καταναλώνουν το ίδιο δημόσιο επίπεδο αντί να αντιγράφουν ξεχωριστό πίνακα.

OpenAPI και συμβόλαιο schema