Semak sumber skema Rivya API v1, peraturan keserasian, medan awam, dan kontrak JSON OpenAPI baca sahaja.

Rivya API v1 menyediakan kontrak skema baca sahaja di:

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

Laluan ini menghasilkan kontrak awam. Ia tidak membaca data sesi pengguna, menghantar tugasan model atau mendedahkan data akaun peribadi.

Sumber kontrak

Kontrak ini diterbitkan daripada:

skema permintaan API awam
kod ralat awam
lapisan rujukan model API awam
katalog model yang sama digunakan oleh /api/v1/models

Senarai model adalah dinamik. Jangan bina integrasi yang bergantung pada kiraan model yang ditulis secara manual.

Dasar versi

Versi API semasa ialah v1.

Perubahan yang serasi dengan versi terdahulu boleh merangkumi:

menambah model ke /api/v1/models
menambah medan respons pilihan
menambah parameter permintaan pilihan untuk model
menambah kod ralat awam baharu

Perubahan yang memecahkan keserasian memerlukan versi baharu atau laluan migrasi yang didokumenkan.

Sempadan medan awam

Medan skema awam menggunakan nama awam:

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

Jangan bergantung pada medan storan tugasan dalaman. Medan tersebut bukan sebahagian daripada kontrak awam.

Skema permintaan

POST /api/v1/generations menerima:

model: ID model awam yang diperlukan
prompt: rentetan pilihan, diperlukan oleh banyak model
params: objek pilihan dengan parameter khusus model
client_request_id: rentetan pilihan untuk ID penjejakan anda sendiri

Gunakan Rujukan API Model untuk params khusus model.

Media rujukan yang dikembalikan oleh /api/v1/files berada di dalam params.referenceMediaItems. Skema mendokumenkan url, kind, name pilihan, mimeType pilihan, durationSeconds / durationToken pilihan, width / height / sizeBytes / imageDimensionsToken pilihan, dan framesPerSecond / videoBitrateMbps / videoMetadataToken pilihan. Setiap imej rujukan Image5, Grok Imagine Image 2.0, dan Wan 3.0 memerlukan token imej bertandatangan serta saiz bait terikat daripada respons muat naik asal yang terikat pada model; Layer Decomposition turut menguatkuasakan had geometri yang didokumenkan. Setiap video rujukan Video8 dan Wan 3.0 memerlukan token tempoh bertandatangan serta metadata video bertandatangan daripada respons muat naik asal yang terikat pada model. Rivya tidak menerima medan files peringkat atas dalam POST /api/v1/generations.

POST /api/v1/files menerima data borang multipart dengan file, kind, model pilihan, dan client_request_id pilihan. Responsnya ialah PublicApiFile, termasuk size_bytes, dimensi imej yang boleh bernilai null, image_dimensions_token, serta video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes, dan video_metadata_token yang boleh bernilai null. GET /api/v1/files/{fileId} mengembalikan metadata awam untuk fail yang dimiliki oleh akaun API, tetapi token metadata bertandatangan yang tidak disimpan mungkin bernilai null dan mesti digantikan dengan memuat naik semula fail.

video_metadata_token terikat pada akaun API, model sasaran, URL, jenis MIME, dimensi, kadar bingkai, kadar bit, dan saiz bait muat naik. Ia tidak menggantikan duration_token; video rujukan Video8 dan Wan 3.0 yang menggunakan kedua-dua kontrak mesti memberikan kedua-dua token. Token tempoh audio Wan 3.0 turut mengikat jenis MIME dan saiz bait muat naik.

Untuk wan-3-0-video, params hanya menerima seedance_scene, variant, resolution, aspect_ratio, duration, audio, seed, dan referenceMediaItems. Scene teks, bingkai, dan rujukan saling eksklusif. Tempoh pintar ialah -1, menempah 30 saat, dan tidak sah bersama video rujukan; kunci sebarangan, media tanpa tandatangan, pintasan fail kepada video, dan pintasan pautan kepada video ditolak tanpa pemprosesan alternatif.

POST /api/v1/chat/completions menerima model, message, session_id pilihan, kawalan pilihan, lampiran file_id Files API pilihan, dan client_request_id pilihan. Ia mengembalikan satu mesej pembantu lengkap tanpa penstriman.

POST /api/v1/chat/completions/stream menerima skema permintaan yang sama dan mengembalikan text/event-stream dengan peristiwa session.created, message.delta, message.completed, usage.completed, heartbeat, error, dan done. Chat API v1 tidak menerima tatasusunan messages mentah.

Skema respons

Hasil OpenAPI mendokumenkan bentuk respons awam berikut:

ModelList untuk GET /api/v1/models
PublicApiModel dan ModelParam untuk pemilihan model dan borang parameter
PublicApiFile untuk POST /api/v1/files dan GET /api/v1/files/{fileId}
ReferenceMediaItem untuk parameter penjanaan berasaskan fail
PublicGeneration untuk respons penciptaan dan status
GenerationResult dan GenerationError untuk tugasan yang selesai
ChatCompletionRequest, ChatCompletion, ChatSession, ChatMessage, ChatUsage, ChatCredits, dan skema peristiwa strim Chat untuk Chat API
CreditBalance untuk GET /api/v1/credits
WebhookEndpoint, WebhookEvent, WebhookDelivery, dan WebhookTestResult untuk webhook API bertandatangan
PublicApiError untuk respons ralat yang stabil

Skema ini selamat digunakan untuk pengesahan klien dan ujian integrasi dalaman. TypeScript SDK beta kekal terikat pada skema ini.

Tadbir urus contoh

Contoh curl, JavaScript, dan Python dalam dokumen ini menggunakan nama medan awam yang sama seperti skema:

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

Contoh sembang turut menggunakan:

chat:create
chat:read
file_id

Contoh webhook turut menggunakan:

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

Apabila parameter model berubah, kemas kini katalog model dan pensiri awam terlebih dahulu. Dokumen dan penyahpepijat patut menggunakan lapisan awam yang sama dan bukannya menyalin jadual berasingan.

Kontrak OpenAPI dan Skema