Bruk Rivya Chat API for ikke-streamende eller SSE-runder, API-opprettede økter, file_id-bildevedlegg og tokenbasert credit-oppgjør.

Bruk POST /api/v1/chat/completions for ett komplett ikke-streamende chat-svar, eller POST /api/v1/chat/completions/stream for Server-Sent Events.

Chat API er øktbasert. Utelat session_id for å starte en ny API-chatøkt. Send med en returnert session_id for å fortsette den samme API-opprettede økten.

Nåværende omfang

Chat API v1 støtter:

ikke-streamende assistentsvar
SSE-streaming med text/event-stream
API-opprettede chatøkter
reservasjon av kontocredits og endelig tokenbasert oppgjør
valgfritt nettsøk, reasoning effort og thought mode når den valgte modellen støtter det
bildevedlegg gjennom Files API file_id-verdier

Chat API v1 støtter ikke:

rå messages-historikk levert av brukeren
videreføring av chatøkter som bare finnes i Studio
vilkårlige eksterne URL-er for vedlegg
Chat webhook-hendelser

Påkrevde scopes

Bruk en API-nøkkel med:

chat:create
chat:read

Nye nøkler som opprettes i Settings, inkluderer begge scopene som standard. Eldre nøkler må kanskje opprettes på nytt før Chat API kan kalles.

Opprett en chat completion

curl https://rivya.ai/api/v1/chat/completions \
  -H "Authorization: Bearer rvya_sk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: chat-turn-001" \
  -d '{
    "model": "gpt-5-2-chat",
    "message": "Write a concise launch plan for a new product image campaign",
    "client_request_id": "chat-001"
  }'

Respons:

{
  "id": "chatcmpl_...",
  "object": "chat.completion",
  "session_id": "session_id",
  "model": "gpt-5-2-chat",
  "created_at": "2026-05-11T00:00:00.000Z",
  "message": {
    "id": "assistant_message_id",
    "role": "assistant",
    "content": "..."
  },
  "usage": {
    "input_tokens": 1200,
    "output_tokens": 320,
    "total_tokens": 1520
  },
  "credits": {
    "reserved": 3,
    "final": 2
  }
}

Stream en chat completion

Bruk POST /api/v1/chat/completions/stream når serveren din vil motta assistentdeltaer etter hvert som de kommer:

curl -N https://rivya.ai/api/v1/chat/completions/stream \
  -H "Authorization: Bearer rvya_sk_..." \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -H "Idempotency-Key: chat-stream-001" \
  -d '{
    "model": "gpt-5-2-chat",
    "message": "Write a concise launch plan for a new product image campaign",
    "client_request_id": "chat-stream-001"
  }'

Streamende svar bruker Content-Type: text/event-stream; charset=utf-8.

Hendelser:

Event	Betydning
`session.created`	API-nøkkel, modell, økt, vedlegg, rate limit og credit-reservasjon er kontrollert og godkjent.
`message.delta`	Et visningsdelta for assistentmeldingen. Dette er ikke en lagret melding ennå.
`message.completed`	Assistentmeldingen ble lagret i den API-opprettede økten.
`usage.completed`	Tokenbruk og endelige credits ble gjort opp.
`heartbeat`	Keepalive-hendelse under lange pauser.
`error`	Offentlig API-feilkonvolutt for en feil etter at streaming startet.
`done`	Streamen ble fullført.

Eksempelstream:

event: session.created
data: {"request_id":"req_...","session_id":"session_id","model":"gpt-5-2-chat"}

event: message.delta
data: {"request_id":"req_...","session_id":"session_id","delta":"Draft ","index":0}

event: message.completed
data: {"request_id":"req_...","session_id":"session_id","message":{"id":"assistant_message_id","role":"assistant","content":"Draft ...","created_at":"2026-05-11T00:00:00.000Z"}}

event: usage.completed
data: {"request_id":"req_...","session_id":"session_id","usage":{"input_tokens":1200,"output_tokens":320,"total_tokens":1520},"credits":{"reserved":3,"final":2}}

event: done
data: {"request_id":"req_...","ok":true}

Hvis en feil skjer etter den første SSE-hendelsen, sender streamen event: error og lukkes:

event: error
data: {"error":{"code":"internal_error","message":"The request could not be completed.","requestId":"req_..."}}

Hvis klienten kobler fra før fullføring, stopper Rivya den pågående genereringsstreamen når det er mulig. Delvise deltaer lagres ikke som endelig assistentmelding. Hvis serveren allerede har lagret message.completed, kan sluttresultatet leses senere med GET /api/v1/chat/sessions/{sessionId}.

Fortsett en økt

Bruk den returnerte session_id:

curl https://rivya.ai/api/v1/chat/completions \
  -H "Authorization: Bearer rvya_sk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: chat-turn-002" \
  -d '{
    "model": "gpt-5-2-chat",
    "session_id": "session_id",
    "message": "Now turn that into a 5-step execution checklist."
  }'

Økten må tilhøre den samme Rivya-kontoen og må være opprettet av Public API. Chat API returnerer eller fortsetter ikke chatøkter som bare finnes i Studio.

Bildevedlegg

Chatvedlegg bruker Files API-oppføringer, ikke eksterne URL-er.

Last opp et bilde med POST /api/v1/files.
Bruk den returnerte id som attachments[].file_id.

{
  "model": "gpt-5-2-chat",
  "message": "Review this product photo and suggest a cleaner editorial direction.",
  "attachments": [
    {
      "file_id": "file_..."
    }
  ]
}

Filen må tilhøre samme konto, ha kind: "image" og være tilgjengelig. Modeller som ikke støtter bildevedlegg, returnerer chat_attachment_not_supported.

Valgfrie kontroller

{
  "model": "gpt-5-2-chat",
  "message": "Compare three launch options.",
  "enable_web_search": false,
  "reasoning_effort": "default",
  "thought_mode": "default"
}

Støtte for kontroller varierer etter modell. Les /api/v1/models og sjekk chat_capabilities før du viser kontroller i brukergrensesnittet ditt.

List opp økter

Bruk GET /api/v1/chat/sessions med en nøkkel som inkluderer chat:read.

curl https://rivya.ai/api/v1/chat/sessions \
  -H "Authorization: Bearer rvya_sk_..."

Dette returnerer bare API-opprettede økter:

{
  "object": "list",
  "data": [
    {
      "id": "session_id",
      "object": "chat.session",
      "model": "gpt-5-2-chat",
      "tool_slug": null,
      "title": "Write a concise launch plan...",
      "controls": {
        "enable_web_search": false,
        "reasoning_effort": null,
        "thought_mode": null
      },
      "created_at": "2026-05-11T00:00:00.000Z",
      "updated_at": "2026-05-11T00:00:00.000Z",
      "last_message_at": "2026-05-11T00:00:00.000Z"
    }
  ]
}

Hent en økt

Bruk GET /api/v1/chat/sessions/{sessionId} for å lese én API-opprettet økt og de lagrede meldingene i den.

curl https://rivya.ai/api/v1/chat/sessions/session_id \
  -H "Authorization: Bearer rvya_sk_..."

Responsen inkluderer lagrede bruker- og assistentmeldinger. Den eksponerer ikke interne provider-felt.

Idempotens

Bruk Idempotency-Key for hver produksjonsforespørsel til POST /api/v1/chat/completions og POST /api/v1/chat/completions/stream.

Hvis et nytt forsøk bruker samme nøkkel og samme body, kan Rivya returnere den lagrede responsen uten å opprette en ny melding eller bruke credits på nytt. Hvis den samme nøkkelen gjenbrukes med andre inndata, returnerer API-et idempotency_conflict.

Ved streamingforsøk spiller Rivya ikke av historiske tokendeltaer på nytt. En fullført avspilling returnerer en minimal SSE-sekvens med session.created, message.completed, usage.completed og done.

Vanlige feil

Code	Betydning
`chat_model_not_supported`	Den valgte modellen er ikke tilgjengelig for Chat API.
`chat_session_conflict`	Økten kan ikke brukes for denne forespørselen.
`chat_attachment_not_supported`	Vedlegget mangler, eies ikke av kontoen, er ikke et bilde eller støttes ikke av modellen.
`insufficient_credits`	Kontoen har ikke nok credits for denne runden.
`idempotency_conflict`	Idempotensnøkkelen ble gjenbrukt med andre inndata.

Chat API