OpenAPI-sopimus ja tietorakenne

Rivya API v1 tarjoaa vain lukuun tarkoitetun tietorakennesopimuksen osoitteessa:

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

Tämä reitti on julkinen sopimustulos. Se ei lue käyttäjän istuntodataa, ei lähetä mallitöitä eikä paljasta yksityisiä tilitietoja.

Sopimuksen lähteet

Sopimus johdetaan näistä:

• julkisen API:n pyyntöschemat

• julkiset virhekoodit

• julkinen API-malliviitekerros

• sama mallikatalogi, jota /api/v1/models käyttää

Malliluettelo on dynaaminen. Älä rakenna integraatioita käsin kirjoitetun mallimäärän varaan.

Versiokäytäntö

Nykyinen API-versio on v1.

Taaksepäin yhteensopiviin muutoksiin voi kuulua:

• mallin lisääminen endpointtiin /api/v1/models

• valinnaisen vastauskentän lisääminen

• valinnaisen pyyntöparametrin lisääminen mallille

• uuden julkisen virhekoodin lisääminen

Rikkovat muutokset vaativat uuden version tai dokumentoidun migraatiopolun.

Julkisten kenttien raja

Julkisen tietorakenteen kentät käyttävät julkisia nimiä:

• id

• status

• model

• session_id

• message

• usage

• reserved_credits

• final_credits

• created_at

• updated_at

• result

• error

Älä nojaa sisäisiin tehtävien tallennuskenttiin. Ne eivät ole osa julkista sopimusta.

Pyynnön tietorakenne

POST /api/v1/generations hyväksyy:

• model: pakollinen julkinen mallitunnus

• prompt: valinnainen string, jota monet mallit vaativat

• params: valinnainen objekti mallikohtaisilla parametreilla

• client_request_id: valinnainen string omaa trace ID:tä varten

Käytä mallien API-viitettä mallikohtaisiin params-arvoihin.

Rajapintareitin /api/v1/files palauttama viitemedia kuuluu params.referenceMediaItems-rakenteen sisään. Tietorakenne määrittelee kentät url, kind, valinnaiset name ja mimeType, valinnaiset durationSeconds / durationToken, valinnaiset width / height / sizeBytes / imageDimensionsToken sekä valinnaiset framesPerSecond / videoBitrateMbps / videoMetadataToken. Jokainen Image5-, Grok Imagine Image 2.0- tai Wan 3.0 -viitekuva vaatii alkuperäisen malliin sidotun latausvastauksen allekirjoitetun kuvatunnisteen ja siihen sidotun tavukoon; Layer Decomposition noudattaa lisäksi dokumentoituja geometriarajojaan. Jokainen Video8- tai Wan 3.0 -viitevideo vaatii alkuperäisen malliin sidotun latausvastauksen allekirjoitetun kestotunnisteen ja allekirjoitetut videometatiedot. Rivya ei hyväksy ylätason files-kenttää pyynnössä POST /api/v1/generations.

POST /api/v1/files hyväksyy multipart form data -datan kentillä file, kind, valinnainen model ja valinnainen client_request_id. Vastaus on PublicApiFile, johon kuuluvat size_bytes, nullable-kuvamittojen kentät, image_dimensions_token, nullable-kentät video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes ja video_metadata_token. GET /api/v1/files/{fileId} palauttaa julkiset metatiedot API-tilin omistamille tiedostoille, mutta tallentamatta jäänyt allekirjoitettu metadatatoken voi olla null, jolloin se on korvattava lataamalla tiedosto uudelleen.

video_metadata_token sidotaan API-tiliin, kohdemalliin, URL-osoitteeseen, MIME-tyyppiin, mittoihin, kuvataajuuteen, bittinopeuteen ja ladatun tiedoston tavukokoon. Se ei korvaa duration_token-arvoa; molempia sopimuksia käyttävien Video8- ja Wan 3.0 -videoreferenssien on annettava molemmat tokenit. Wan 3.0 -audion kestotoken sitoo myös MIME-tyypin ja latauksen tavukoon.

Mallille wan-3-0-video params hyväksyy vain kentät seedance_scene, variant, resolution, aspect_ratio, duration, audio, seed ja referenceMediaItems. Teksti-, kuva- ja referenssitilat ovat toisensa poissulkevia. Älykäs kesto on -1, varaa 30 sekuntia ja on virheellinen referenssivideon kanssa; mielivaltaiset avaimet, allekirjoittamaton media sekä tiedostosta videoksi- ja linkistä videoksi -pikareitit hylätään ilman vaihtoehtoista käsittelyä.

POST /api/v1/chat/completions hyväksyy kentät model, message, valinnainen session_id, valinnaiset ohjaimet, valinnaiset Files API file_id -liitteet ja valinnainen client_request_id. Se palauttaa yhden kokonaisen ei-streamaavan assistant-viestin.

POST /api/v1/chat/completions/stream hyväksyy saman pyyntöscheman ja palauttaa text/event-stream-vastauksen tapahtumilla session.created, message.delta, message.completed, usage.completed, heartbeat, error ja done. Chat API v1 ei hyväksy raakaa messages-taulukkoa.

Vastausschemat

OpenAPI-tulos dokumentoi nämä julkiset vastausmuodot:

• ModelList endpointille GET /api/v1/models

• PublicApiModel ja ModelParam mallin valintaan ja parametrilomakkeisiin

• PublicApiFile endpointeille POST /api/v1/files ja GET /api/v1/files/{fileId}

• ReferenceMediaItem tiedostopohjaisille generointiparametreille

• PublicGeneration luonti- ja tilavastauksille

• GenerationResult ja GenerationError valmistuneille tehtäville

• ChatCompletionRequest, ChatCompletion, ChatSession, ChatMessage, ChatUsage, ChatCredits ja chat-streamin tapahtumaschemat Chat API:lle

• CreditBalance endpointille GET /api/v1/credits

• WebhookEndpoint, WebhookEvent, WebhookDelivery ja WebhookTestResult allekirjoitetuille API-webhookeille

• PublicApiError vakaille virhevastauksille

Schemaa voi käyttää turvallisesti asiakasvalidointiin ja sisäisiin integraatiotesteihin. TypeScript SDK -beta pysyy tämän scheman rajaamana.

Esimerkkien hallinta

Näiden dokumenttien curl-, JavaScript- ja Python-esimerkit käyttävät samoja julkisia kenttänimiä kuin tietorakenne:

• Authorization: Bearer rvya_sk_...

• Idempotency-Key

• model

• prompt

• message

• session_id

• params

• client_request_id

Chat-esimerkit käyttävät lisäksi:

• chat:create

• chat:read

• file_id

Webhook-esimerkit käyttävät lisäksi:

• Rivya-Webhook-Signature

• Rivya-Webhook-Timestamp

• webhooks:manage

Kun malliparametri muuttuu, päivitä ensin mallikatalogi ja julkinen serializer. Dokumenttien ja debuggerin tulee käyttää samaa julkista kerrosta erillisen taulukon kopioimisen sijaan.

Liittyvät sivut

• API-mallit

• Rivyan TypeScript SDK

• Mallien API-viite

• Luo generointi

• Chat API

• API-webhookit

• API-virheet ja rajoitukset