Chat API

Použijte POST /api/v1/chat/completions pro jednu úplnou nestreamovanou odpověď chatu, nebo POST /api/v1/chat/completions/stream pro události odesílané serverem přes SSE.

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.

Stránka popisuje implementovaný kontrakt veřejného API v1. Přístup za běhu stále závisí na zapnutém veřejném API v nasazení, aktivním API klíči účtu a dostupném API stavu vybraného modelu. Před produkčním požadavkem zkontrolujte živý seznam modelů.

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:

• nezpracovanou historii 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á oprávnění

Použijte API klíč s:

chat:create
chat:read

Nové klíče vytvořené v nastavení obsahují obě oprávnění 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í odpovědi chatu

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

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": "claude-sonnet-5-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:

Ukázkový stream:

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":"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": "claude-sonnet-5-chat",
    "session_id": "session_id",
    "message": "Teď z toho udělej prováděcí kontrolní seznam o 5 krocích."
  }'

Relace musí patřit ke stejnému účtu Rivya a musí být vytvořena přes veřejné 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.

1. Nahrajte obrázek pomocí POST /api/v1/files.

2. Použijte vrácené id jako attachments[].file_id.

{
  "model": "<image-capable-chat-model-id>",
  "message": "Zkontroluj tuto produktovou fotografii a navrhni čistší editorialní směr.",
  "attachments": [
    {
      "file_id": "file_..."
    }
  ]
}

Soubor musí patřit stejnému účtu, mít kind: "image" a být dostupný. Zástupný identifikátor nahraďte aktuálně dostupným chatovacím modelem, jehož záznam v /api/v1/models hlásí podporu obrazů v chat_capabilities. Model claude-sonnet-5-chat použitý v ostatních příkladech je pouze textový a pro tento požadavek se nehodí. Modely bez podpory obrazů vracejí chat_attachment_not_supported.

Volitelné ovládací prvky

{
  "model": "claude-sonnet-5-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": "claude-sonnet-5-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

Související stránky

• Modely API

• Files API

• Kredity API

• Chyby a limity API

• OpenAPI a smlouva schématu