Chat API

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.

Denne siden dokumenterer den implementerte Public API v1-kontrakten. Kjøretidstilgang krever fortsatt at Public API er aktivert for distribusjonen, at kontoen har en aktiv API-nøkkel, og at den valgte modellen rapporterer tilgjengelig API-status. Sjekk den aktive modellisten før du sender en produksjonsforespørsel.

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, resonneringsnivå og tankemodus når den valgte modellen støtter det

• bildevedlegg gjennom Fil-API-ens 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 Innstillinger, inkluderer begge tilgangsområdene 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": "claude-sonnet-5-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": "claude-sonnet-5-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": "claude-sonnet-5-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:

Eksempelstream:

event: session.created
data: {"request_id":"req_...","session_id":"session_id","model":"claude-sonnet-5-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": "claude-sonnet-5-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 oppføringer fra Fil-API-et, ikke eksterne URL-er.

1. Last opp et bilde med POST /api/v1/files.

2. Bruk den returnerte id som attachments[].file_id.

{
  "model": "<image-capable-chat-model-id>",
  "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. Erstatt plassholderen med en tilgjengelig chatmodell der oppføringen i /api/v1/models rapporterer støtte for bildevedlegg i chat_capabilities. claude-sonnet-5-chat er teksteksemplet som brukes ellers på siden, og må ikke brukes til denne vedleggsforespørselen. Modeller som ikke støtter bildevedlegg, returnerer chat_attachment_not_supported.

Valgfrie kontroller

{
  "model": "claude-sonnet-5-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": "claude-sonnet-5-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 leverandørfelt.

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 forespørselskropp, kan Rivya returnere den lagrede responsen uten å opprette en ny melding eller bruke kreditter 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

Relaterte sider

• API-modeller

• Fil-API

• API-kreditter

• API-feil og begrensninger

• OpenAPI- og schema-kontrakt