Tinjau sumber schema Rivya API v1, aturan kompatibilitas, field publik, dan kontrak OpenAPI JSON read-only.

Rivya API v1 mengekspos kontrak schema read-only di:

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

Route ini adalah output kontrak publik. Route ini tidak membaca data session pengguna, tidak mengirim pekerjaan model, dan tidak mengekspos data akun privat.

Sumber Kontrak

Kontrak diturunkan dari:

schema request API publik
kode error publik
layer referensi model API publik
katalog model yang sama dengan yang digunakan oleh /api/v1/models

Daftar model bersifat dinamis. Jangan membangun integrasi yang bergantung pada jumlah model yang ditulis manual.

Kebijakan Versi

Versi API saat ini adalah v1.

Perubahan yang kompatibel ke belakang dapat mencakup:

menambahkan model ke /api/v1/models
menambahkan field respons opsional
menambahkan parameter request opsional untuk model
menambahkan kode error publik baru

Perubahan breaking membutuhkan versi baru atau jalur migrasi yang terdokumentasi.

Batas Field Publik

Field schema publik memakai nama publik:

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

Jangan bergantung pada field penyimpanan tugas internal. Field tersebut bukan bagian dari kontrak publik.

Schema Request

POST /api/v1/generations menerima:

model: ID model publik yang wajib diisi
prompt: string opsional, dibutuhkan oleh banyak model
params: objek opsional dengan parameter spesifik model
client_request_id: string opsional untuk trace ID Anda sendiri

Gunakan Referensi API Model untuk params spesifik model.

Media referensi yang dikembalikan oleh /api/v1/files berada di dalam params.referenceMediaItems. Schema mendokumentasikan url, kind, name opsional, mimeType opsional, durationSeconds opsional, dan durationToken opsional. Rivya tidak menerima field files tingkat atas di POST /api/v1/generations.

POST /api/v1/files menerima multipart form data dengan file, kind, model opsional, dan client_request_id opsional. Responsnya adalah PublicApiFile. GET /api/v1/files/{fileId} mengembalikan metadata file publik yang sama untuk file milik akun API.

POST /api/v1/chat/completions menerima model, message, session_id opsional, kontrol opsional, lampiran file_id Files API opsional, dan client_request_id opsional. Endpoint ini mengembalikan satu pesan assistant non-streaming yang lengkap.

POST /api/v1/chat/completions/stream menerima schema request yang sama dan mengembalikan text/event-stream dengan event session.created, message.delta, message.completed, usage.completed, heartbeat, error, dan done. Chat API v1 tidak menerima array raw messages.

Schema Respons

Output OpenAPI mendokumentasikan bentuk respons publik berikut:

ModelList untuk GET /api/v1/models
PublicApiModel dan ModelParam untuk pemilihan model dan form parameter
PublicApiFile untuk POST /api/v1/files dan GET /api/v1/files/{fileId}
ReferenceMediaItem untuk parameter generasi berbasis file
PublicGeneration untuk respons pembuatan dan status
GenerationResult dan GenerationError untuk tugas yang selesai
ChatCompletionRequest, ChatCompletion, ChatSession, ChatMessage, ChatUsage, ChatCredits, dan schema event stream Chat untuk Chat API
CreditBalance untuk GET /api/v1/credits
WebhookEndpoint, WebhookEvent, WebhookDelivery, dan WebhookTestResult untuk API webhooks bertanda tangan
PublicApiError untuk respons error stabil

Schema ini aman digunakan untuk validasi klien dan pengujian integrasi internal. Beta TypeScript SDK tetap dibatasi oleh schema ini.

Tata Kelola Contoh

Contoh curl, JavaScript, dan Python dalam docs ini memakai nama field publik yang sama dengan schema:

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

Contoh Chat juga memakai:

chat:create
chat:read
file_id

Contoh webhook juga memakai:

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

Saat parameter model berubah, perbarui katalog model dan public serializer terlebih dahulu. Docs dan debugger sebaiknya memakai layer publik yang sama, bukan menyalin tabel terpisah.

Kontrak OpenAPI dan Schema