Przejrzyj źródła schematu Rivya API v1, reguły kompatybilności, pola publiczne i tylko do odczytu kontrakt OpenAPI JSON.

Rivya API v1 udostępnia kontrakt schematu tylko do odczytu pod adresem:

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

Ta trasa jest publicznym wyjściem kontraktu. Nie odczytuje danych sesji użytkownika, nie wysyła zadań modeli i nie ujawnia prywatnych danych konta.

Źródła Kontraktu

Kontrakt pochodzi z:

publicznych schematów żądań API
publicznych kodów błędów
publicznej warstwy referencji modeli API
tego samego katalogu modeli, którego używa /api/v1/models

Lista modeli jest dynamiczna. Nie buduj integracji zależnych od ręcznie wpisanej liczby modeli.

Polityka Wersji

Bieżąca wersja API to v1.

Zmiany kompatybilne wstecz mogą obejmować:

dodanie modelu do /api/v1/models
dodanie opcjonalnego pola odpowiedzi
dodanie opcjonalnego parametru żądania dla modelu
dodanie nowego publicznego kodu błędu

Zmiany łamiące kompatybilność wymagają nowej wersji albo udokumentowanej ścieżki migracji.

Granica Pól Publicznych

Publiczne pola schematu używają publicznych nazw:

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

Nie polegaj na wewnętrznych polach przechowywania zadań. Nie są częścią publicznego kontraktu.

Schemat Żądania

POST /api/v1/generations akceptuje:

model: wymagany publiczny ID modelu
prompt: opcjonalny string, wymagany przez wiele modeli
params: opcjonalny obiekt z parametrami specyficznymi dla modelu
client_request_id: opcjonalny string dla Twojego własnego ID śledzenia

Użyj Referencji modeli API dla params specyficznych dla modelu.

Media referencyjne zwrócone przez /api/v1/files należą do params.referenceMediaItems. Schemat dokumentuje url, kind, opcjonalne name, opcjonalne mimeType, opcjonalne durationSeconds / durationToken, opcjonalne width / height / sizeBytes / imageDimensionsToken oraz opcjonalne framesPerSecond / videoBitrateMbps / videoMetadataToken. Każdy obraz referencyjny Image5, Grok Imagine Image 2.0 lub Wan 3.0 wymaga podpisanego tokenu obrazu i powiązanego rozmiaru w bajtach z pierwotnej odpowiedzi uploadu powiązanego z modelem; Layer Decomposition egzekwuje również udokumentowane limity geometrii. Każdy referencyjny plik wideo Video8 lub Wan 3.0 wymaga podpisanego tokenu czasu trwania i podpisanych metadanych wideo z pierwotnej odpowiedzi uploadu powiązanego z modelem. Rivya nie akceptuje pola files na najwyższym poziomie w POST /api/v1/generations.

POST /api/v1/files akceptuje multipart form data z file, kind, opcjonalnym model i opcjonalnym client_request_id. Odpowiedzią jest PublicApiFile, w tym size_bytes, opcjonalne wymiary obrazu, image_dimensions_token oraz opcjonalne video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes i video_metadata_token. GET /api/v1/files/{fileId} zwraca publiczne metadane pliku dla plików należących do konta API, ale nieutrwalony podpisany token metadanych może mieć wartość null i trzeba go zastąpić przez ponowne przesłanie pliku.

video_metadata_token jest powiązany z kontem API, modelem docelowym, adresem URL, typem MIME, wymiarami, liczbą klatek na sekundę, przepływnością i rozmiarem uploadu w bajtach. Nie zastępuje duration_token; referencyjne pliki wideo Video8 i Wan 3.0 korzystające z obu kontraktów muszą zawierać oba tokeny. Tokeny czasu trwania audio Wan 3.0 są również powiązane z typem MIME i rozmiarem uploadu w bajtach.

Dla wan-3-0-video obiekt params akceptuje wyłącznie seedance_scene, variant, resolution, aspect_ratio, duration, audio, seed i referenceMediaItems. Sceny tekstu, klatek i referencji wzajemnie się wykluczają. Inteligentny czas trwania ma wartość -1, rezerwuje 30 sekund i jest niedozwolony z referencyjnym plikiem wideo; dowolne klucze, niepodpisane media oraz skróty przekształcania pliku w wideo lub linku w wideo są odrzucane zgodnie z zasadą bezpiecznego zamknięcia przy błędzie.

POST /api/v1/chat/completions akceptuje model, message, opcjonalne session_id, opcjonalne kontrole, opcjonalne załączniki Files API file_id i opcjonalne client_request_id. Zwraca jedną pełną niestreamingową wiadomość asystenta.

POST /api/v1/chat/completions/stream akceptuje ten sam schemat żądania i zwraca text/event-stream ze zdarzeniami session.created, message.delta, message.completed, usage.completed, heartbeat, error i done. Chat API v1 nie akceptuje surowej tablicy messages.

Schematy Odpowiedzi

Wyjście OpenAPI dokumentuje te publiczne kształty odpowiedzi:

ModelList dla GET /api/v1/models
PublicApiModel i ModelParam dla wyboru modelu i formularzy parametrów
PublicApiFile dla POST /api/v1/files i GET /api/v1/files/{fileId}
ReferenceMediaItem dla parametrów generowania opartych na plikach
PublicGeneration dla odpowiedzi tworzenia i statusu
GenerationResult i GenerationError dla ukończonych zadań
ChatCompletionRequest, ChatCompletion, ChatSession, ChatMessage, ChatUsage, ChatCredits oraz schematy zdarzeń strumienia Chat dla Chat API
CreditBalance dla GET /api/v1/credits
WebhookEndpoint, WebhookEvent, WebhookDelivery i WebhookTestResult dla podpisanych API webhooks
PublicApiError dla stabilnych odpowiedzi błędów

Schemat jest bezpieczny do użycia w walidacji klienta i wewnętrznych testach integracyjnych. Beta TypeScript SDK pozostaje ograniczona tym schematem.

Zarządzanie Przykładami

Przykłady curl, JavaScript i Python w tej dokumentacji używają tych samych publicznych nazw pól co schemat:

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

Przykłady Chat dodatkowo używają:

chat:create
chat:read
file_id

Przykłady webhooków dodatkowo używają:

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

Gdy zmienia się parametr modelu, najpierw zaktualizuj katalog modeli i publiczny serializer. Dokumentacja i debugger powinny korzystać z tej samej publicznej warstwy zamiast kopiować osobną tabelę.

Kontrakt OpenAPI i schemat