Chat API

Használd a POST /api/v1/chat/completions végpontot egy teljes, egyszerre visszaadott chatválaszhoz, a POST /api/v1/chat/completions/stream végpontot pedig 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.

Az oldal a megvalósított Public API v1 szerződést dokumentálja. A futásidejű hozzáférés továbbra is attól függ, hogy a Public API engedélyezve van-e a telepítésben, a fióknak van-e aktív API-kulcsa, és a kiválasztott modell élő API-állapota elérhető-e. Éles kérés előtt ellenőrizd az aktuális modelllistát.

Jelenlegi hatókör

A Chat API v1 támogatja:

• egyszerre visszaadott asszisztensválaszok

• SSE-adatfolyam 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, következtetési erősség és gondolkodási mód, 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 jogosultsági körök

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 jogosultsági kört tartalmazzák. Régebbi kulcsokat lehet, hogy újra kell létrehozni a Chat API hívása előtt.

Chatválasz 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": "claude-sonnet-5-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": "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
  }
}

Chatválasz fogadása adatfolyamban

Használd a POST /api/v1/chat/completions/stream végpontot, amikor a szervered már érkezés közben szeretné megkapni az asszisztens válaszrészleteit:

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

Az adatfolyamban érkező válaszok Content-Type: text/event-stream; charset=utf-8 típust használnak.

Események:

Példa az adatfolyamra:

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}

Ha az első SSE-esemény után hiba történik, az adatfolyam 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ő válaszadatfolyamot. A részleges válaszok 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": "claude-sonnet-5-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 végponttal.

2. A visszakapott id értéket használd attachments[].file_id mezőként.

{
  "model": "<image-capable-chat-model-id>",
  "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 és elérhető állapottal. A helyőrzőt olyan jelenleg elérhető chatmodellre cseréld, amelynek /api/v1/models bejegyzése képtámogatást jelez a chat_capabilities mezőben. A más példákban használt claude-sonnet-5-chat csak szöveges modell, ehhez a kéréshez nem használható. A képet nem támogató modellek chat_attachment_not_supported hibát adnak.

Opcionális vezérlők

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

A vezérlők támogatása modellenként eltér. Olvasd le a /api/v1/models végpont válaszát, és ellenőrizd a chat_capabilities mezőt, mielőtt vezérlőket jelenítesz meg a felületen.

Munkamenetek listázása

Használd a GET /api/v1/chat/sessions végpontot olyan kulccsal, amely tartalmazza a chat:read jogosultsági kört.

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

Munkamenet lekérése

Használd a GET /api/v1/chat/sessions/{sessionId} végpontot 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. A külső szolgáltatók belső mezőit nem teszi láthatóvá.

Idempotencia

Használj Idempotency-Key fejlécet 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 kéréstörzset 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.

Adatfolyamos újrapróbálkozásnál a Rivya nem játssza vissza a korábbi tokenrészleteket. Egy befejezett kérés ismételt válasza rövid SSE-eseménysort 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