Bekijk Rivya API v1-schemabronnen, compatibiliteitsregels, publieke velden en het read-only OpenAPI JSON-contract.

Rivya API v1 stelt een read-only schemacontract beschikbaar op:

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

Deze route is een publieke contractoutput. Hij leest geen gebruikerssessiedata, dient geen modeltaken in en stelt geen private accountdata bloot.

Contractbronnen

Het contract is afgeleid van:

publieke API-requestschema's
publieke foutcodes
de publieke API-modelreferentielaag
dezelfde modelcatalogus die door /api/v1/models wordt gebruikt

De modellenlijst is dynamisch. Bouw geen integraties die afhankelijk zijn van een handmatig geschreven modelaantal.

Versiebeleid

De huidige API-versie is v1.

Backward-compatible wijzigingen kunnen bestaan uit:

een model toevoegen aan /api/v1/models
een optioneel responseveld toevoegen
een optionele requestparameter toevoegen voor een model
een nieuwe publieke foutcode toevoegen

Breaking changes vereisen een nieuwe versie of een gedocumenteerd migratiepad.

Publieke veldgrens

Publieke schemavelden gebruiken publieke namen:

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

Vertrouw niet op interne opslagvelden van taken. Die zijn geen onderdeel van het publieke contract.

Requestschema

POST /api/v1/generations accepteert:

model: vereiste publieke model-ID
prompt: optionele string, vereist door veel modellen
params: optioneel object met modelspecifieke parameters
client_request_id: optionele string voor je eigen trace-ID

Gebruik Model API-referentie voor modelspecifieke params.

Referentiemedia die door /api/v1/files worden teruggegeven, horen in params.referenceMediaItems. Het schema documenteert url, kind, optionele name, optionele mimeType, optionele durationSeconds / durationToken, optionele width / height / sizeBytes / imageDimensionsToken en optionele framesPerSecond / videoBitrateMbps / videoMetadataToken. Voor elke Image5-, Grok Imagine Image 2.0- of Wan 3.0-referentieafbeelding zijn het ondertekende afbeeldingstoken en de gekoppelde bestandsgrootte uit de oorspronkelijke modelgebonden uploadresponse vereist; Layer Decomposition dwingt daarnaast de gedocumenteerde geometrische limieten af. Voor elke Video8- of Wan 3.0-referentievideo zijn het ondertekende duurtoken en de ondertekende videometadata uit de oorspronkelijke modelgebonden uploadresponse vereist. Rivya accepteert geen top-level files-veld in POST /api/v1/generations.

POST /api/v1/files accepteert multipart form data met file, kind, optionele model en optionele client_request_id. De response is PublicApiFile, inclusief size_bytes, nullable afbeeldingsafmetingen, image_dimensions_token, nullable video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes en video_metadata_token. GET /api/v1/files/{fileId} retourneert publieke metadata voor bestanden die eigendom zijn van het API-account, maar een ondertekend metadatatoken dat niet is opgeslagen kan null zijn en moet door een nieuwe upload worden vervangen.

video_metadata_token is gebonden aan het API-account, het doelmodel, de URL, het MIME-type, de afmetingen, de framerate, de bitrate en het aantal uploadbytes. Het vervangt duration_token niet; Video8- en Wan 3.0-referentievideo's die beide contracten gebruiken, moeten beide tokens meesturen. De audioduurtokens van Wan 3.0 zijn ook gebonden aan het MIME-type en het aantal uploadbytes.

Voor wan-3-0-video accepteert params alleen seedance_scene, variant, resolution, aspect_ratio, duration, audio, seed en referenceMediaItems. De tekst-, frames- en referentiescènes sluiten elkaar uit. Intelligente duur is -1, reserveert 30 seconden en is ongeldig met een referentievideo; willekeurige sleutels, niet-ondertekende media en snelkoppelingen voor bestand-naar-video of link-naar-video worden afgewezen volgens het principe dat fouten standaard tot blokkering leiden.

POST /api/v1/chat/completions accepteert model, message, optionele session_id, optionele controls, optionele Files API file_id-attachments en optionele client_request_id. Het retourneert één volledig non-streaming assistantbericht.

POST /api/v1/chat/completions/stream accepteert hetzelfde requestschema en retourneert text/event-stream met session.created, message.delta, message.completed, usage.completed, heartbeat, error en done events. Chat API v1 accepteert geen raw messages array.

Responseschema's

De OpenAPI-output documenteert deze publieke responseshapes:

ModelList voor GET /api/v1/models
PublicApiModel en ModelParam voor modelselectie en parameterformulieren
PublicApiFile voor POST /api/v1/files en GET /api/v1/files/{fileId}
ReferenceMediaItem voor file-backed generatieparameters
PublicGeneration voor create- en statusresponses
GenerationResult en GenerationError voor voltooide taken
ChatCompletionRequest, ChatCompletion, ChatSession, ChatMessage, ChatUsage, ChatCredits en Chat stream event schemas voor Chat API
CreditBalance voor GET /api/v1/credits
WebhookEndpoint, WebhookEvent, WebhookDelivery en WebhookTestResult voor ondertekende API-webhooks
PublicApiError voor stabiele foutresponses

Het schema is veilig te gebruiken voor clientvalidatie en interne integratietests. De TypeScript SDK beta blijft door dit schema begrensd.

Voorbeeldgovernance

curl-, JavaScript- en Python-voorbeelden in deze docs gebruiken dezelfde publieke veldnamen als het schema:

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

Chatvoorbeelden gebruiken daarnaast:

chat:create
chat:read
file_id

Webhookvoorbeelden gebruiken daarnaast:

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

Wanneer een modelparameter verandert, werk dan eerst de modelcatalogus en public serializer bij. De docs en debugger moeten dezelfde publieke laag gebruiken in plaats van een aparte tabel te kopiëren.

OpenAPI- en schemacontract