Použijte Rivya Chat API pro nestreamované nebo SSE tahy, relace vytvořené přes API, obrazové přílohy file_id a kreditní vyrovnání podle tokenů.

Použijte POST /api/v1/chat/completions pro jednu úplnou nestreamovanou odpověď chatu, nebo POST /api/v1/chat/completions/stream pro Server-Sent Events.

Chat API je založené na relacích. Vynechte session_id, pokud chcete spustit novou chatovou relaci přes API. Předáním vráceného session_id můžete pokračovat ve stejné relaci vytvořené přes API.

Aktuální rozsah

Chat API v1 podporuje:

nestreamované odpovědi asistenta
SSE streamování s text/event-stream
chatové relace vytvořené přes API
rezervaci kreditu účtu a konečné vyrovnání podle počtu tokenů
volitelné webové vyhledávání, úroveň usuzování a režim myšlenek, pokud je vybraný model podporuje
obrazové přílohy přes hodnoty file_id z Files API

Chat API v1 nepodporuje:

historii raw messages dodanou uživatelem
pokračování v relacích pouze ze Studia
libovolné externí URL příloh
webhook události pro Chat

Požadované scope

Použijte API klíč s:

chat:create
chat:read

Nové klíče vytvořené v Settings obsahují oba scope ve výchozím nastavení. Starší klíče může být nutné před voláním Chat API znovu vytvořit.

Vytvoř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": "gpt-5-2-chat",
    "message": "Napiš stručný plán uvedení nové kampaně produktových obrázků",
    "client_request_id": "chat-001"
  }'

Odpověď:

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

Streamování Chat Completion

Použijte POST /api/v1/chat/completions/stream, když váš server potřebuje číst přírůstky odpovědi asistenta hned při generování:

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": "Napiš stručný plán uvedení nové kampaně produktových obrázků",
    "client_request_id": "chat-stream-001"
  }'

Streamované odpovědi používají Content-Type: text/event-stream; charset=utf-8.

Události:

Event	Význam
`session.created`	API klíč, model, relace, přílohy, limit rychlosti a rezervace kreditu prošly kontrolou.
`message.delta`	Zobrazovaný přírůstek zprávy asistenta. Ještě nejde o potvrzenou zprávu.
`message.completed`	Zpráva asistenta byla uložena do relace vytvořené přes API.
`usage.completed`	Spotřeba tokenů a konečné kredity byly vyrovnány.
`heartbeat`	Událost keepalive při delších prodlevách.
`error`	Obálka chyby Public API pro selhání po zahájení streamování.
`done`	Stream byl úspěšně dokončen.

Ukázkový 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":"Návrh ","index":0}

event: message.completed
data: {"request_id":"req_...","session_id":"session_id","message":{"id":"assistant_message_id","role":"assistant","content":"Návrh ...","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}

Pokud po první SSE události dojde k chybě, stream odešle event: error a potom se uzavře:

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

Pokud se klient před dokončením odpojí, Rivya podle možností zastaví probíhající generovací stream. Dílčí přírůstky se neukládají jako finální zpráva asistenta. Pokud server už potvrdil message.completed, finální výsledek lze později přečíst pomocí GET /api/v1/chat/sessions/{sessionId}.

Pokračování v relaci

Použijte vrácené 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": "Teď z toho udělej pětikrokový prováděcí checklist."
  }'

Relace musí patřit ke stejnému účtu Rivya a musí být vytvořena přes Public API. Relace chatu pouze ze Studia Chat API nevrací ani v nich nepokračuje.

Obrazové přílohy

Přílohy chatu používají záznamy Files API, ne externí URL.

Nahrajte obrázek pomocí POST /api/v1/files.
Použijte vrácené id jako attachments[].file_id.

{
  "model": "gpt-5-2-chat",
  "message": "Zkontroluj tuto produktovou fotografii a navrhni čistší editorialní směr.",
  "attachments": [
    {
      "file_id": "file_..."
    }
  ]
}

Soubor musí patřit ke stejnému účtu, mít kind: "image" a být dostupný. Modely, které obrazové přílohy nepodporují, vracejí chat_attachment_not_supported.

Volitelné ovládací prvky

{
  "model": "gpt-5-2-chat",
  "message": "Porovnej tři možnosti uvedení na trh.",
  "enable_web_search": false,
  "reasoning_effort": "default",
  "thought_mode": "default"
}

Podpora ovládacích prvků se liší podle modelu. Před jejich zobrazením ve vlastním UI si přečtěte /api/v1/models a zkontrolujte chat_capabilities.

Výpis relací

Použijte GET /api/v1/chat/sessions s klíčem, který obsahuje chat:read.

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

Vrací pouze relace vytvořené přes API:

{
  "object": "list",
  "data": [
    {
      "id": "session_id",
      "object": "chat.session",
      "model": "gpt-5-2-chat",
      "tool_slug": null,
      "title": "Napiš stručný plán uvedení...",
      "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"
    }
  ]
}

Načtení jedné relace

Použijte GET /api/v1/chat/sessions/{sessionId} pro načtení jedné relace vytvořené přes API a jejích potvrzených zpráv.

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

Odpověď obsahuje potvrzené zprávy uživatele a asistenta. Nezpřístupňuje interní pole poskytovatele.

Idempotence

Používejte Idempotency-Key pro každý produkční požadavek POST /api/v1/chat/completions a POST /api/v1/chat/completions/stream.

Pokud opakovaný pokus použije stejný klíč a stejné tělo, Rivya může vrátit uloženou odpověď, aniž by vytvořila další zprávu nebo znovu spotřebovala kredity. Pokud je stejný klíč znovu použit s jiným vstupem, API vrátí idempotency_conflict.

Při opakování streamovaného požadavku Rivya znovu nepřehrává historické tokenové přírůstky. Dokončené přehrání vrátí minimální SSE sekvenci se session.created, message.completed, usage.completed a done.

Běžné chyby

Code	Význam
`chat_model_not_supported`	Vybraný model není pro Chat API dostupný.
`chat_session_conflict`	Relaci nelze pro tento požadavek použít.
`chat_attachment_not_supported`	Příloha chybí, nepatří účtu, není obrázek nebo ji model nepodporuje.
`insufficient_credits`	Účet nemá dost kreditů pro tento tah.
`idempotency_conflict`	Idempotentní klíč byl znovu použit s jiným vstupem.

Chat API