Gennemgå Rivya API v1's schema-kilder, kompatibilitetsregler, offentlige felter og den read-only OpenAPI JSON-kontrakt.

Rivya API v1 eksponerer en read-only schema-kontrakt på:

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

Denne route er et offentligt kontraktoutput. Den læser ikke brugerens sessiondata, indsender ikke modeljobs og eksponerer ikke private kontodata.

Kontraktkilder

Kontrakten er afledt af:

offentlige API-request schemas
offentlige fejlkoder
det offentlige API-modelreferencelag
det samme modelkatalog, der bruges af /api/v1/models

Modellisten er dynamisk. Byg ikke integrationer, der afhænger af et manuelt skrevet modelantal.

Versionspolitik

Den aktuelle API-version er v1.

Bagudkompatible ændringer kan omfatte:

tilføjelse af en model til /api/v1/models
tilføjelse af et valgfrit svarfelt
tilføjelse af en valgfri request-parameter for en model
tilføjelse af en ny offentlig fejlkode

Breaking changes kræver en ny version eller en dokumenteret migreringsvej.

Offentlig feltgrænse

Offentlige schema-felter bruger offentlige navne:

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

Afhæng ikke af interne task storage-felter. De er ikke en del af den offentlige kontrakt.

Request schema

POST /api/v1/generations accepterer:

model: påkrævet offentlig model-ID
prompt: valgfri string, påkrævet af mange modeller
params: valgfrit objekt med modelspecifikke parametre
client_request_id: valgfri string til dit eget trace-ID

Brug Model API Reference for modelspecifikke params.

Referencemedier returneret af /api/v1/files hører hjemme i params.referenceMediaItems. Schemaet dokumenterer url, kind, valgfri name, valgfri mimeType, valgfri durationSeconds / durationToken, valgfri width / height / sizeBytes / imageDimensionsToken og valgfri framesPerSecond / videoBitrateMbps / videoMetadataToken. Hvert referencebillede til Image5, Grok Imagine Image 2.0 eller Wan 3.0 kræver det signerede billedtoken og den bundne filstørrelse fra det oprindelige modelbundne uploadsvar; Layer Decomposition håndhæver desuden de dokumenterede geometriske grænser. Hver Video8- eller Wan 3.0-referencevideo kræver det signerede varighedstoken og de signerede videometadata fra det oprindelige modelbundne uploadsvar. Rivya accepterer ikke et top-level files-felt i POST /api/v1/generations.

POST /api/v1/files accepterer multipart form data med file, kind, valgfri model og valgfri client_request_id. Svaret er PublicApiFile, inklusive size_bytes, nullable billeddimensioner, image_dimensions_token, nullable video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes og video_metadata_token. GET /api/v1/files/{fileId} returnerer offentlige metadata for filer, der ejes af API-kontoen, men et signeret metadatatoken, som ikke blev gemt, kan være null og skal erstattes ved at uploade filen igen.

video_metadata_token er bundet til API-kontoen, målmodellen, URL'en, MIME-typen, dimensionerne, billedfrekvensen, bitraten og uploadstørrelsen i bytes. Det erstatter ikke duration_token; Video8- og Wan 3.0-referencevideoer, der bruger begge kontrakter, skal levere begge tokens. Varighedstokens for Wan 3.0-lyd binder også MIME-type og uploadstørrelse i bytes.

For wan-3-0-video accepterer params kun seedance_scene, variant, resolution, aspect_ratio, duration, audio, seed og referenceMediaItems. Tekst-, billed- og referencescener er gensidigt udelukkende. Intelligent varighed er -1, reserverer 30 sekunder og er ugyldig med referencevideo; vilkårlige nøgler, usignerede medier og genveje fra fil til video eller link til video afvises uden alternativ behandling.

POST /api/v1/chat/completions accepterer model, message, valgfri session_id, valgfri kontroller, valgfri Files API-vedhæftninger med file_id og valgfri client_request_id. Det returnerer én komplet ikke-streaming assistant-besked.

POST /api/v1/chat/completions/stream accepterer samme request schema og returnerer text/event-stream med events for session.created, message.delta, message.completed, usage.completed, heartbeat, error og done. Chat API v1 accepterer ikke et råt messages-array.

Response schemas

OpenAPI-outputtet dokumenterer disse offentlige response shapes:

ModelList for GET /api/v1/models
PublicApiModel og ModelParam for modelvalg og parameterformularer
PublicApiFile for POST /api/v1/files og GET /api/v1/files/{fileId}
ReferenceMediaItem for filbaserede genereringsparametre
PublicGeneration for create- og status-svar
GenerationResult og GenerationError for completed tasks
ChatCompletionRequest, ChatCompletion, ChatSession, ChatMessage, ChatUsage, ChatCredits og Chat stream event schemas for Chat API
CreditBalance for GET /api/v1/credits
WebhookEndpoint, WebhookEvent, WebhookDelivery og WebhookTestResult for signerede API webhooks
PublicApiError for stabile fejlsvar

Schemaet er sikkert at bruge til klientvalidering og interne integrationstests. TypeScript SDK beta forbliver begrænset af dette schema.

Eksempel-governance

curl-, JavaScript- og Python-eksempler i disse docs bruger de samme offentlige feltnavne som schemaet:

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

Chat-eksempler bruger desuden:

chat:create
chat:read
file_id

Webhook-eksempler bruger desuden:

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

Når en modelparameter ændres, skal modelkataloget og den offentlige serializer opdateres først. Docs og debugger bør bruge det samme offentlige lag i stedet for at kopiere en separat tabel.

OpenAPI- og schema-kontrakt