Gebruik Rivya Chat API voor non-streaming of SSE-turns, API-aangemaakte sessies, file_id-afbeeldingsbijlagen en tokengebaseerde creditafrekening.

Gebruik POST /api/v1/chat/completions voor één volledige non-streaming chatresponse, of POST /api/v1/chat/completions/stream voor Server-Sent Events.

Chat API is sessiegebaseerd. Laat session_id weg om een nieuwe API-chatsessie te starten. Geef een teruggegeven session_id mee om dezelfde API-aangemaakte sessie voort te zetten.

Huidige scope

Chat API v1 ondersteunt:

non-streaming assistant-antwoorden
SSE-streaming met text/event-stream
API-aangemaakte chatsessies
reservering van accountcredits en uiteindelijke tokengebaseerde afrekening
optionele web search, reasoning effort en thought mode wanneer het geselecteerde model die ondersteunt
afbeeldingsbijlagen via Files API file_id-waarden

Chat API v1 ondersteunt niet:

door de gebruiker aangeleverde raw messages-geschiedenis
doorgaan met Studio-only chatsessies
willekeurige externe attachment-URL's
chat-webhookgebeurtenissen

Vereiste scopes

Gebruik een API-sleutel met:

chat:create
chat:read

Nieuwe sleutels die in Settings worden aangemaakt, bevatten beide scopes standaard. Oudere sleutels moeten mogelijk opnieuw worden aangemaakt voordat je Chat API aanroept.

Een Chat Completion aanmaken

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"
  }'

Response:

{
  "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
  }
}

Een Chat Completion streamen

Gebruik POST /api/v1/chat/completions/stream wanneer je server assistant-delta's wil ontvangen zodra ze binnenkomen:

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"
  }'

Streaming responses gebruiken Content-Type: text/event-stream; charset=utf-8.

Events:

Event	Betekenis
`session.created`	De checks voor API-sleutel, model, sessie, attachments, rate limit en creditreservering zijn geslaagd.
`message.delta`	Een display-delta voor het assistantbericht. Dit is nog geen gecommitte bericht.
`message.completed`	Het assistantbericht is gecommit naar de API-aangemaakte sessie.
`usage.completed`	Tokengebruik en uiteindelijke credits zijn afgerekend.
`heartbeat`	Keepalive-event tijdens lange pauzes.
`error`	Public API error envelope voor een fout nadat streaming is gestart.
`done`	De stream is succesvol voltooid.

Voorbeeldstream:

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}

Als er na het eerste SSE-event een fout optreedt, stuurt de stream event: error en sluit daarna:

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

Als de client vóór voltooiing de verbinding verbreekt, stopt Rivya de lopende generatiestream waar mogelijk. Gedeeltelijke delta's worden niet opgeslagen als definitief assistantbericht. Als de server message.completed al heeft gecommit, kan het eindresultaat later worden gelezen met GET /api/v1/chat/sessions/{sessionId}.

Een sessie voortzetten

Gebruik de teruggegeven 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."
  }'

De sessie moet bij hetzelfde Rivya-account horen en door Public API zijn aangemaakt. Studio-only chatsessies worden niet teruggegeven of voortgezet door Chat API.

Afbeeldingsbijlagen

Chatbijlagen gebruiken Files API-records, geen externe URL's.

Upload een afbeelding met POST /api/v1/files.
Gebruik de teruggegeven id als attachments[].file_id.

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

Het bestand moet bij hetzelfde account horen, kind: "image" hebben en beschikbaar zijn. Modellen die geen afbeeldingsbijlagen ondersteunen, retourneren chat_attachment_not_supported.

Optionele controls

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

Control-ondersteuning verschilt per model. Lees /api/v1/models en controleer chat_capabilities voordat je controls in je UI toont.

Sessies lijst tonen

Gebruik GET /api/v1/chat/sessions met een sleutel die chat:read bevat.

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

Dit retourneert alleen API-aangemaakte sessies:

{
  "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"
    }
  ]
}

Een sessie ophalen

Gebruik GET /api/v1/chat/sessions/{sessionId} om één API-aangemaakte sessie en de gecommitte berichten ervan te lezen.

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

De response bevat gecommitte user- en assistantberichten. Interne provider-velden worden niet blootgesteld.

Idempotentie

Gebruik Idempotency-Key voor elke productieaanvraag naar POST /api/v1/chat/completions en POST /api/v1/chat/completions/stream.

Als een retry dezelfde sleutel en dezelfde body gebruikt, kan Rivya de opgeslagen response teruggeven zonder nog een bericht te maken of opnieuw credits te verbruiken. Als dezelfde sleutel met andere input wordt hergebruikt, retourneert de API idempotency_conflict.

Voor streaming retries speelt Rivya geen historische token-delta's opnieuw af. Een voltooide replay retourneert een minimale SSE-sequentie met session.created, message.completed, usage.completed en done.

Veelvoorkomende fouten

Code	Betekenis
`chat_model_not_supported`	Het geselecteerde model is niet beschikbaar voor Chat API.
`chat_session_conflict`	De sessie kan niet voor deze request worden gebruikt.
`chat_attachment_not_supported`	De attachment ontbreekt, is niet eigendom van het account, is geen afbeelding of wordt niet door het model ondersteund.
`insufficient_credits`	Het account heeft niet genoeg credits voor de beurt.
`idempotency_conflict`	De idempotency key is hergebruikt met andere input.

Chat API