Rivya API v1 şema kaynaklarını, uyumluluk kurallarını, public alanları ve salt okunur OpenAPI JSON sözleşmesini inceleyin.

Rivya API v1 salt okunur şema sözleşmesini şu adreste sunar:

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

Bu route public sözleşme çıktısıdır. Kullanıcı session verilerini okumaz, model işleri göndermez ve özel hesap verilerini açığa çıkarmaz.

Sözleşme Kaynakları

Sözleşme şunlardan türetilir:

public API istek şemaları
public hata kodları
public API model referans katmanı
/api/v1/models tarafından kullanılan aynı model kataloğu

Model listesi dinamiktir. Elle yazılmış model sayısına bağlı entegrasyonlar kurmayın.

Versiyon Politikası

Geçerli API versiyonu v1.

Geriye dönük uyumlu değişiklikler şunları içerebilir:

/api/v1/models içine model ekleme
isteğe bağlı bir response alanı ekleme
bir model için isteğe bağlı request parametresi ekleme
yeni bir public hata kodu ekleme

Breaking change'ler yeni bir versiyon veya belgelenmiş bir migration yolu gerektirir.

Public Alan Sınırı

Public şema alanları public adlar kullanır:

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

Internal task storage alanlarına bağlı kalmayın. Bunlar public sözleşmenin parçası değildir.

Request Şeması

POST /api/v1/generations şunları kabul eder:

model: gerekli public model ID'si
prompt: isteğe bağlı string, birçok model için gereklidir
params: modele özel parametreler içeren isteğe bağlı object
client_request_id: kendi trace ID'niz için isteğe bağlı string

Modele özel params için Model API Referansı kullanın.

/api/v1/files tarafından döndürülen referans medya params.referenceMediaItems içinde yer alır. Şema url, kind, isteğe bağlı name, isteğe bağlı mimeType, isteğe bağlı durationSeconds / durationToken, isteğe bağlı width / height / sizeBytes / imageDimensionsToken ve isteğe bağlı framesPerSecond / videoBitrateMbps / videoMetadataToken alanlarını belgeler. Image5, Grok Imagine Image 2.0 veya Wan 3.0 için kullanılan her referans görüntüsü, özgün modele bağlı yükleme yanıtındaki imzalı görüntü token'ını ve buna bağlı bayt boyutunu gerektirir; Layer Decomposition ayrıca belgelenen geometri limitlerini uygular. Her Video8 veya Wan 3.0 referans videosu, özgün modele bağlı yükleme yanıtındaki imzalı süre token'ını ve imzalı video metadata bilgilerini gerektirir. Rivya, POST /api/v1/generations içinde üst düzey files alanı kabul etmez.

POST /api/v1/files, file, kind, isteğe bağlı model ve isteğe bağlı client_request_id içeren multipart form data kabul eder. Yanıt; size_bytes, null olabilen görüntü boyutları, image_dimensions_token, null olabilen video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes ve video_metadata_token dahil olmak üzere PublicApiFile şeklindedir. GET /api/v1/files/{fileId}, API hesabına ait dosyaların public metadata bilgilerini döndürür; ancak kalıcı olarak saklanmamış bir imzalı metadata token'ı null olabilir ve yeniden yüklenerek yenilenmelidir.

video_metadata_token; API hesabına, hedef modele, URL'ye, MIME türüne, boyutlara, kare hızına, bit hızına ve yükleme bayt boyutuna bağlıdır. duration_token yerine geçmez; iki sözleşmeyi de kullanan Video8 ve Wan 3.0 referans videoları her iki token'ı da sağlamalıdır. Wan 3.0 ses süre token'ları ayrıca MIME türüne ve yükleme bayt boyutuna bağlıdır.

wan-3-0-video için params yalnızca seedance_scene, variant, resolution, aspect_ratio, duration, audio, seed ve referenceMediaItems alanlarını kabul eder. Metin, kare ve referans sahneleri birbirini dışlar. Akıllı süre -1 değeridir, 30 saniye ayırır ve referans videosuyla kullanılamaz; rastgele anahtarlar, imzasız medya ve dosyadan videoya veya bağlantıdan videoya kısayollar hata durumunda kapalı kalma ilkesiyle reddedilir.

POST /api/v1/chat/completions, model, message, isteğe bağlı session_id, isteğe bağlı kontroller, isteğe bağlı Files API file_id ekleri ve isteğe bağlı client_request_id kabul eder. Tam bir non-streaming asistan mesajı döndürür.

POST /api/v1/chat/completions/stream aynı request şemasını kabul eder ve session.created, message.delta, message.completed, usage.completed, heartbeat, error ve done olaylarıyla text/event-stream döndürür. Chat API v1 ham messages array kabul etmez.

Response Şemaları

OpenAPI çıktısı şu public response şekillerini belgeler:

ModelList, GET /api/v1/models için
PublicApiModel ve ModelParam, model seçimi ve parametre formları için
PublicApiFile, POST /api/v1/files ve GET /api/v1/files/{fileId} için
ReferenceMediaItem, dosya destekli oluşturma parametreleri için
PublicGeneration, oluşturma ve durum response'ları için
GenerationResult ve GenerationError, tamamlanmış görevler için
ChatCompletionRequest, ChatCompletion, ChatSession, ChatMessage, ChatUsage, ChatCredits ve Chat stream event şemaları, Chat API için
CreditBalance, GET /api/v1/credits için
WebhookEndpoint, WebhookEvent, WebhookDelivery ve WebhookTestResult, imzalı API webhook'ları için
PublicApiError, kararlı hata response'ları için

Şema, client doğrulaması ve internal integration testleri için güvenle kullanılabilir. TypeScript SDK beta bu şemayla sınırlı kalır.

Örnek Yönetimi

Bu dokümanlardaki curl, JavaScript ve Python örnekleri şemayla aynı public alan adlarını kullanır:

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

Chat örnekleri ayrıca şunları kullanır:

chat:create
chat:read
file_id

Webhook örnekleri ayrıca şunları kullanır:

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

Bir model parametresi değiştiğinde önce model kataloğunu ve public serializer'ı güncelleyin. Dokümanlar ve debugger, ayrı bir tablo kopyalamak yerine aynı public katmanı tüketmelidir.

OpenAPI ve Şema Sözleşmesi