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 / durationToken opsional, width / height / sizeBytes / imageDimensionsToken opsional, serta framesPerSecond / videoBitrateMbps / videoMetadataToken opsional. Setiap gambar referensi Image5, Grok Imagine Image 2.0, atau Wan 3.0 memerlukan token gambar bertanda tangan dan ukuran byte terikat dari respons unggahan asli yang terikat ke model; Layer Decomposition juga menerapkan batas geometrinya dalam dokumentasi. Setiap video referensi Video8 dan Wan 3.0 memerlukan token durasi bertanda tangan dan metadata video bertanda tangan dari respons unggahan asli yang terikat ke model. 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, termasuk size_bytes, dimensi gambar yang dapat 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 dapat bernilai null. GET /api/v1/files/{fileId} mengembalikan metadata publik untuk file milik akun API, tetapi token metadata bertanda tangan yang tidak disimpan dapat bernilai null dan harus diganti dengan mengunggah ulang file.

video_metadata_token terikat ke akun API, model tujuan, URL, jenis MIME, dimensi, frame rate, bitrate, dan ukuran byte unggahan. Token ini tidak menggantikan duration_token; video referensi Video8 dan Wan 3.0 yang menggunakan kedua kontrak harus menyertakan kedua token tersebut. Token durasi audio Wan 3.0 juga mengikat jenis MIME dan ukuran byte unggahan.

Untuk wan-3-0-video, params hanya menerima seedance_scene, variant, resolution, aspect_ratio, duration, audio, seed, dan referenceMediaItems. Mode teks, frame, dan referensi saling eksklusif. Durasi cerdas adalah -1, mereservasi 30 detik, dan tidak valid bersama video referensi. Parameter lain yang tidak dikenal, media tanpa tanda tangan, pintasan file-to-video, serta pintasan link-to-video akan ditolak; jika validasi gagal, akses ditutup.

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