OpenAPI och schemakontrakt

Rivya API v1 exponerar ett skrivskyddat schemakontrakt på:

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

Den här routen är en offentlig kontraktsutdata. Den läser inte användarsessionsdata, skickar inte in modelljobb och exponerar inte privata kontodata.

Kontraktskällor

Kontraktet härleds från:

• offentliga API-requestscheman

• offentliga felkoder

• det offentliga API-lagret för modellreferens

• samma modellkatalog som används av /api/v1/models

Modellistan är dynamisk. Bygg inte integrationer som beror på ett manuellt skrivet modellantal.

Versionspolicy

Den aktuella API-versionen är v1.

Bakåtkompatibla ändringar kan omfatta:

• att lägga till en modell i /api/v1/models

• att lägga till ett valfritt svarsfält

• att lägga till en valfri requestparameter för en modell

• att lägga till en ny offentlig felkod

Brytande ändringar kräver en ny version eller en dokumenterad migreringsväg.

Gräns för offentliga fält

Offentliga schemafält använder offentliga namn:

• id

• status

• model

• session_id

• message

• usage

• reserved_credits

• final_credits

• created_at

• updated_at

• result

• error

Förlita dig inte på interna lagringsfält för uppgifter. De ingår inte i det offentliga kontraktet.

Requestschema

POST /api/v1/generations accepterar:

• model: obligatoriskt offentligt modell-ID

• prompt: valfri sträng, krävs av många modeller

• params: valfritt objekt med modellspecifika parametrar

• client_request_id: valfri sträng för ditt eget trace-ID

Använd modellreferensen för API för modellspecifika params.

Referensmedia som returneras av /api/v1/files hör hemma i params.referenceMediaItems. Schemat dokumenterar url, kind, valfritt name, valfritt mimeType, valfritt durationSeconds / durationToken, valfritt width / height / sizeBytes / imageDimensionsToken och valfritt framesPerSecond / videoBitrateMbps / videoMetadataToken. Varje referensbild för Image5, Grok Imagine Image 2.0 eller Wan 3.0 kräver signerad bildtoken och bunden byte-storlek från det ursprungliga modellbundna uppladdningssvaret; Layer Decomposition tillämpar även sina dokumenterade geometrigränser. Varje Video8- eller Wan 3.0-referensvideo kräver signerad varaktighetstoken och signerad videometadata från det ursprungliga modellbundna uppladdningssvaret. Rivya accepterar inte ett toppnivåfält files i POST /api/v1/generations.

POST /api/v1/files accepterar multipart form data med file, kind, valfritt model och valfritt client_request_id. Svaret är PublicApiFile och innehåller size_bytes, nullbara bildmått, image_dimensions_token, nullbara video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes och video_metadata_token. GET /api/v1/files/{fileId} returnerar offentlig metadata för filer som ägs av API-kontot, men en signerad metadatatoken som inte har sparats kan vara null och måste ersättas genom en ny uppladdning.

video_metadata_token är bunden till API-kontot, målmodellen, URL:en, MIME-typen, måtten, bildfrekvensen, bithastigheten och uppladdningens byte-storlek. Den ersätter inte duration_token; Video8- och Wan 3.0-referensvideor som använder båda kontrakten måste ange båda tokenvärdena. Varaktighetstoken för Wan 3.0-ljud binder även MIME-typ och uppladdningens byte-storlek.

För wan-3-0-video accepterar params endast seedance_scene, variant, resolution, aspect_ratio, duration, audio, seed och referenceMediaItems. Text-, bildrute- och referensscener är ömsesidigt uteslutande. Intelligent varaktighet är -1, reserverar 30 sekunder och är ogiltig med referensvideo; godtyckliga nycklar, osignerade medier samt genvägar från fil till video och länk till video avvisas utan alternativ bearbetning.

POST /api/v1/chat/completions accepterar model, message, valfritt session_id, valfria kontroller, valfria Files API-bilagor via file_id och valfritt client_request_id. Det returnerar ett komplett icke-streamande assistentmeddelande.

POST /api/v1/chat/completions/stream accepterar samma requestschema och returnerar text/event-stream med händelserna session.created, message.delta, message.completed, usage.completed, heartbeat, error och done. Chat API v1 accepterar inte en rå messages-array.

Svarsscheman

OpenAPI-utdata dokumenterar dessa offentliga svarsformer:

• ModelList för GET /api/v1/models

• PublicApiModel och ModelParam för modellval och parameterformulär

• PublicApiFile för POST /api/v1/files och GET /api/v1/files/{fileId}

• ReferenceMediaItem för filstödda genereringsparametrar

• PublicGeneration för svar vid skapande och status

• GenerationResult och GenerationError för slutförda uppgifter

• ChatCompletionRequest, ChatCompletion, ChatSession, ChatMessage, ChatUsage, ChatCredits och Chat stream event schemas för Chat API

• CreditBalance för GET /api/v1/credits

• WebhookEndpoint, WebhookEvent, WebhookDelivery och WebhookTestResult för signerade API-webhooks

• PublicApiError för stabila felsvar

Schemat kan användas för klientvalidering och interna integrationstester. Betaversionen av TypeScript SDK följer fortfarande detta schema.

Exempelstyrning

curl-, JavaScript- och Python-exempel i dessa dokument använder samma offentliga fältnamn som schemat:

• Authorization: Bearer rvya_sk_...

• Idempotency-Key

• model

• prompt

• message

• session_id

• params

• client_request_id

Chat-exempel använder dessutom:

• chat:create

• chat:read

• file_id

Webhook-exempel använder dessutom:

• Rivya-Webhook-Signature

• Rivya-Webhook-Timestamp

• webhooks:manage

När en modellparameter ändras, uppdatera modellkatalogen och den offentliga serializern först. Dokumentationen och debuggern ska konsumera samma offentliga lager i stället för att kopiera en separat tabell.

Relaterade sidor

• API-modeller

• Rivya TypeScript SDK

• Modellreferens för API

• Skapa generation

• Chat API

• API-webhooks

• API-fel och gränser