Chat API

Használd a POST /api/v1/chat/completions endpointot egy teljes, nem streamelt chatválaszhoz, vagy a POST /api/v1/chat/completions/stream endpointot Server-Sent Events válaszokhoz.

A Chat API munkamenet-alapú. Hagyd el a session_id mezőt új API chatmunkamenet indításához. Egy visszakapott session_id átadásával ugyanazt az API által létrehozott munkamenetet folytathatod.

Jelenlegi hatókör

A Chat API v1 támogatja:

• nem streamelt asszisztensválaszok
• SSE streaming text/event-stream használatával
• API-val létrehozott chatmunkamenetek
• fiókkredit-foglalás és végső tokenalapú elszámolás
• opcionális webes keresés, reasoning effort és thought mode, ha a kiválasztott modell támogatja
• kép-csatolmányok a Files API file_id értékein keresztül

A Chat API v1 nem támogatja:

• felhasználó által megadott nyers messages előzményeket
• kizárólag Studióban létrehozott chatmunkamenetek folytatását
• tetszőleges külső csatolmány URL-eket
• Chat webhook eseményeket

Szükséges scope-ok

Olyan API-kulcsot használj, amely tartalmazza:

chat:create
chat:read

A Beállításokban létrehozott új kulcsok alapértelmezés szerint mindkét scope-ot tartalmazzák. Régebbi kulcsokat lehet, hogy újra kell létrehozni a Chat API hívása előtt.

Chat completion létrehozása

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

Válasz:

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

Chat completion streamelése

Használd a POST /api/v1/chat/completions/stream endpointot, amikor a szervered az asszisztens deltáit érkezés közben szeretné megkapni:

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

A streamelt válaszok Content-Type: text/event-stream; charset=utf-8 típust használnak.

Események:

Példa stream:

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}

Ha az első SSE esemény után hiba történik, a stream event: error eseményt küld, majd lezárul:

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

Ha a kliens a befejezés előtt leválik, a Rivya lehetőség szerint leállítja a folyamatban lévő generálási streamet. A részleges delták nem mentődnek végső asszisztensüzenetként. Ha a szerver már véglegesítette a message.completed eseményt, a végeredmény később a GET /api/v1/chat/sessions/{sessionId} hívással olvasható.

Munkamenet folytatása

Használd a visszakapott session_id értéket:

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

A munkamenetnek ugyanahhoz a Rivya-fiókhoz kell tartoznia, és a Public API-nak kellett létrehoznia. A kizárólag Studióban létrehozott chatmunkameneteket a Chat API nem adja vissza és nem folytatja.

Kép-csatolmányok

A chat-csatolmányok Files API rekordokat használnak, nem külső URL-eket.

1. Tölts fel egy képet a POST /api/v1/files endpointtal.
2. A visszakapott id értéket használd attachments[].file_id mezőként.

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

A fájlnak ugyanahhoz a fiókhoz kell tartoznia, kind: "image" értékkel kell rendelkeznie, és elérhetőnek kell lennie. Azok a modellek, amelyek nem támogatják a kép-csatolmányokat, chat_attachment_not_supported választ adnak.

Opcionális vezérlők

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

A vezérlőtámogatás modellenként eltér. Olvasd a /api/v1/models endpointot, és ellenőrizd a chat_capabilities mezőt, mielőtt vezérlőket jelenítesz meg a UI-ban.

Munkamenetek listázása

Használd a GET /api/v1/chat/sessions endpointot olyan kulccsal, amely tartalmazza a chat:read scope-ot.

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

Ez csak API-val létrehozott munkameneteket ad vissza:

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

Munkamenet lekérése

Használd a GET /api/v1/chat/sessions/{sessionId} endpointot egy API-val létrehozott munkamenet és véglegesített üzenetei olvasásához.

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

A válasz tartalmazza a véglegesített felhasználói és asszisztensüzeneteket. Belső providerszintű mezőket nem tesz láthatóvá.

Idempotencia

Használj Idempotency-Key headert minden éles POST /api/v1/chat/completions és POST /api/v1/chat/completions/stream kéréshez.

Ha egy újrapróbálkozás ugyanazt a kulcsot és ugyanazt a body-t használja, a Rivya visszaadhatja a tárolt választ anélkül, hogy újabb üzenetet hozna létre vagy újra krediteket fogyasztana. Ha ugyanazt a kulcsot más bemenettel használod újra, az API idempotency_conflict választ ad.

Streaming újrapróbálkozásoknál a Rivya nem játssza vissza a korábbi token deltákat. Egy befejezett replay minimális SSE szekvenciát ad vissza session.created, message.completed, usage.completed és done eseményekkel.

Gyakori hibák

Kapcsolódó oldalak

• API modellek
• Files API
• API kreditek
• API hibák és limitek
• OpenAPI és séma szerződés