Chat API

Käytä POST /api/v1/chat/completions -endpointtia yhteen valmiiseen ei-streamaavaan chat-vastaukseen tai POST /api/v1/chat/completions/stream -endpointtia Server-Sent Events -vastauksille.

Chat API perustuu istuntoihin. Jätä session_id pois, kun haluat aloittaa uuden API-chat-istunnon. Anna palautettu session_id, kun haluat jatkaa samaa API:n luomaa istuntoa.

Nykyinen scope

Chat API v1 tukee:

• ei-streamaavia assistant-vastauksia
• SSE-streamausta text/event-stream-sisällöllä
• API:n luomia chat-istuntoja
• tilin krediittivarauksen ja lopullisen token-pohjaisen selvityksen
• valinnaista verkkohakua, päättelypanosta ja thought mode -tilaa, kun valittu malli tukee niitä
• kuvaliitteitä Files API:n file_id-arvojen kautta

Chat API v1 ei tue:

• käyttäjän toimittamaa raakaa messages-historiaa
• vain Studiossa luotujen chat-istuntojen jatkamista
• mielivaltaisia ulkoisia liite-URL-osoitteita
• Chat-webhook-tapahtumia

Vaaditut scope-oikeudet

Käytä API-avainta, jossa on:

chat:create
chat:read

Asetuksissa luodut uudet avaimet sisältävät molemmat scope-oikeudet oletuksena. Vanhemmat avaimet voi joutua luomaan uudelleen ennen Chat API:n kutsumista.

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

Vastaus:

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

Streamaa chat completion

Käytä POST /api/v1/chat/completions/stream -endpointtia, kun palvelimesi haluaa assistant-deltat sitä mukaa kuin ne saapuvat:

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

Streamaavat vastaukset käyttävät Content-Type: text/event-stream; charset=utf-8.

Tapahtumat:

Esimerkkistream:

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}

Jos virhe tapahtuu ensimmäisen SSE-tapahtuman jälkeen, stream lähettää event: error ja sulkeutuu sitten:

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

Jos asiakas katkaisee yhteyden ennen valmistumista, Rivya pysäyttää käynnissä olevan generointistreamin, kun se on mahdollista. Osittaisia deltoja ei tallenneta lopullisena assistant-viestinä. Jos palvelin on jo tallentanut message.completed-tapahtuman, lopullinen tulos voidaan lukea myöhemmin endpointilla GET /api/v1/chat/sessions/{sessionId}.

Jatka istuntoa

Käytä palautettua session_id-arvoa:

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

Istunnon täytyy kuulua samalle Rivya-tilille, ja sen täytyy olla Public API:n luoma. Vain Studiossa luotuja chat-istuntoja ei palauteta eikä jatketa Chat API:n kautta.

Kuvaliitteet

Chat-liitteet käyttävät Files API -tietueita, eivät ulkoisia URL-osoitteita.

1. Lataa kuva endpointilla POST /api/v1/files.
2. Käytä palautettua id-arvoa kentässä attachments[].file_id.

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

Tiedoston täytyy kuulua samalle tilille, sillä täytyy olla kind: "image", ja sen täytyy olla saatavilla. Mallit, jotka eivät tue kuvaliitteitä, palauttavat chat_attachment_not_supported.

Valinnaiset ohjaimet

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

Ohjainten tuki vaihtelee mallin mukaan. Lue /api/v1/models ja tarkista chat_capabilities, ennen kuin tuot ohjaimet näkyviin käyttöliittymässäsi.

Listaa istunnot

Käytä GET /api/v1/chat/sessions -endpointtia avaimella, joka sisältää chat:read-oikeuden.

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

Tämä palauttaa vain API:n luomat istunnot:

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

Hae istunto

Käytä GET /api/v1/chat/sessions/{sessionId} -endpointtia yhden API:n luoman istunnon ja sen tallennettujen viestien lukemiseen.

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

Vastaus sisältää tallennetut käyttäjän ja assistantin viestit. Se ei paljasta sisäisiä provider-kenttiä.

Idempotenssi

Käytä Idempotency-Key-headeria jokaisessa tuotannon POST /api/v1/chat/completions- ja POST /api/v1/chat/completions/stream -pyynnössä.

Jos uusintayritys käyttää samaa avainta ja samaa bodya, Rivya voi palauttaa tallennetun vastauksen luomatta uutta viestiä tai kuluttamatta krediittejä uudelleen. Jos samaa avainta käytetään uudelleen eri syötteellä, API palauttaa virheen idempotency_conflict.

Streamaavissa uusintayrityksissä Rivya ei toista historiallisia token-deltoja. Valmistunut toisto palauttaa minimaalisen SSE-sekvenssin tapahtumilla session.created, message.completed, usage.completed ja done.

Yleiset virheet

Liittyvät sivut

• API-mallit
• Files API
• API-krediitit
• API-virheet ja rajoitukset
• OpenAPI- ja schema-sopimus