OpenAPI και σύμβαση σχήματος

Το 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: απαιτούμενο δημόσιο αναγνωριστικό μοντέλου

• prompt: προαιρετική συμβολοσειρά, απαιτείται από πολλά μοντέλα

• params: προαιρετικό αντικείμενο με παραμέτρους ειδικές για το μοντέλο

• client_request_id: προαιρετική συμβολοσειρά για το δικό σας αναγνωριστικό ανίχνευσης

Χρησιμοποιήστε την Αναφορά 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 απαιτεί το υπογεγραμμένο token εικόνας και το δεσμευμένο μέγεθος byte από την αρχική απόκριση ανεβάσματος για το συγκεκριμένο μοντέλο· το Layer Decomposition επιβάλλει επίσης τα τεκμηριωμένα γεωμετρικά όριά του. Κάθε βίντεο αναφοράς Video8 και Wan 3.0 απαιτεί το υπογεγραμμένο token διάρκειας και τα υπογεγραμμένα metadata βίντεο από την αρχική απόκριση ανεβάσματος για το συγκεκριμένο μοντέλο. Το Rivya δεν δέχεται top-level πεδίο files στο POST /api/v1/generations.

Το POST /api/v1/files δέχεται multipart form data με file, kind, προαιρετικό model και προαιρετικό client_request_id. Η απόκριση είναι PublicApiFile, που περιλαμβάνει size_bytes, nullable διαστάσεις εικόνας, image_dimensions_token, nullable video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes και video_metadata_token. Το GET /api/v1/files/{fileId} επιστρέφει δημόσια metadata για αρχεία που ανήκουν στον λογαριασμό API, αλλά ένα υπογεγραμμένο token metadata που δεν διατηρήθηκε μπορεί να είναι null και πρέπει να αντικατασταθεί με νέο ανέβασμα.

Το video_metadata_token δεσμεύεται στον λογαριασμό API, στο μοντέλο προορισμού, στο URL, στον τύπο MIME, στις διαστάσεις, στον ρυθμό καρέ, στο bitrate και στο μέγεθος ανεβάσματος σε byte. Δεν αντικαθιστά το duration_token· τα βίντεο αναφοράς Video8 και Wan 3.0 που χρησιμοποιούν και τα δύο συμβόλαια πρέπει να παρέχουν και τα δύο token. Τα token διάρκειας ήχου του Wan 3.0 δεσμεύονται επίσης στον τύπο MIME και στο μέγεθος ανεβάσματος σε byte.

Για το wan-3-0-video, το params δέχεται μόνο seedance_scene, variant, resolution, aspect_ratio, duration, audio, seed και referenceMediaItems. Οι λειτουργίες κειμένου, καρέ και αναφοράς είναι αμοιβαία αποκλειόμενες. Η έξυπνη διάρκεια είναι -1, δεσμεύει 30 δευτερόλεπτα και δεν είναι έγκυρη με βίντεο αναφοράς· αυθαίρετα πεδία, μη υπογεγραμμένα μέσα και συντομεύσεις file-to-video ή link-to-video απορρίπτονται χωρίς εναλλακτική επεξεργασία.

Το POST /api/v1/chat/completions δέχεται model, message, προαιρετικό session_id, προαιρετικά στοιχεία ελέγχου, προαιρετικά συνημμένα file_id του Files API και προαιρετικό 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 τεκμηριώνει τις παρακάτω δημόσιες μορφές απόκρισης:

• 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 για σταθερές αποκρίσεις σφάλματος

Το σχήμα είναι ασφαλές για χρήση σε επαλήθευση από την εφαρμογή-πελάτη και σε εσωτερικές δοκιμές ενσωμάτωσης. Το beta TypeScript SDK εξακολουθεί να οριοθετείται από αυτό το σχήμα.

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

Τα παραδείγματα curl, JavaScript και Python σε αυτή την τεκμηρίωση χρησιμοποιούν τα ίδια δημόσια ονόματα πεδίων με το σχήμα:

• 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 πρέπει να καταναλώνουν το ίδιο δημόσιο επίπεδο αντί να αντιγράφουν ξεχωριστό πίνακα.

Σχετικές σελίδες

• Μοντέλα API

• Rivya TypeScript SDK

• Αναφορά API μοντέλων

• Δημιουργία generation

• Chat API

• API Webhooks

• Σφάλματα και όρια API