Używaj Rivya Chat API do tur niestreamingowych albo SSE, sesji tworzonych przez API, załączników obrazów przez file_id i rozliczania kredytów na podstawie tokenów.

Użyj POST /api/v1/chat/completions, aby uzyskać jedną pełną niestreamingową odpowiedź czatu, albo POST /api/v1/chat/completions/stream dla Server-Sent Events.

Chat API działa na sesjach. Pomiń session_id, aby rozpocząć nową sesję czatu API. Przekaż zwrócone session_id, aby kontynuować tę samą sesję utworzoną przez API.

Bieżący Zakres

Chat API v1 obsługuje:

niestreamingowe odpowiedzi asystenta
streaming SSE z text/event-stream
sesje czatu tworzone przez API
rezerwację kredytów konta i końcowe rozliczenie na podstawie tokenów
opcjonalne wyszukiwanie w sieci, reasoning effort i thought mode, gdy wybrany model je obsługuje
załączniki obrazów przez wartości file_id z Files API

Chat API v1 nie obsługuje:

surowej historii messages dostarczanej przez użytkownika
kontynuowania sesji czatu dostępnych tylko w Studio
dowolnych zewnętrznych adresów URL załączników
zdarzeń webhook Chat

Wymagane Zakresy

Użyj klucza API z:

chat:create
chat:read

Nowe klucze utworzone w Settings domyślnie zawierają oba zakresy. Starsze klucze mogą wymagać ponownego utworzenia przed wywołaniem Chat API.

Utwórz 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"
  }'

Odpowiedź:

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

Streamuj Chat Completion

Użyj POST /api/v1/chat/completions/stream, gdy Twój serwer chce otrzymywać delty asystenta w chwili ich pojawiania się:

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

Odpowiedzi streamingowe używają Content-Type: text/event-stream; charset=utf-8.

Zdarzenia:

Event	Znaczenie
`session.created`	Klucz API, model, sesja, załączniki, limit szybkości i rezerwacja kredytów przeszły weryfikację.
`message.delta`	Delta wyświetlana dla wiadomości asystenta. Nie jest jeszcze zatwierdzoną wiadomością.
`message.completed`	Wiadomość asystenta została zapisana w sesji utworzonej przez API.
`usage.completed`	Użycie tokenów i końcowe kredyty zostały rozliczone.
`heartbeat`	Zdarzenie keepalive podczas długich przerw.
`error`	Publiczna koperta błędu API dla awarii po rozpoczęciu streamingu.
`done`	Strumień zakończył się powodzeniem.

Przykładowy strumień:

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}

Jeśli błąd wystąpi po pierwszym zdarzeniu SSE, strumień wysyła event: error, a następnie się zamyka:

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

Jeśli klient rozłączy się przed zakończeniem, Rivya zatrzyma trwający strumień generowania, gdy będzie to możliwe. Częściowe delty nie są zapisywane jako końcowa wiadomość asystenta. Jeśli serwer zapisał już message.completed, wynik końcowy można później odczytać przez GET /api/v1/chat/sessions/{sessionId}.

Kontynuuj Sesję

Użyj zwróconego 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": "Now turn that into a 5-step execution checklist."
  }'

Sesja musi należeć do tego samego konta Rivya i musi być utworzona przez Public API. Sesje czatu dostępne tylko w Studio nie są zwracane ani kontynuowane przez Chat API.

Załączniki Obrazów

Załączniki Chat używają rekordów Files API, a nie zewnętrznych adresów URL.

Prześlij obraz przez POST /api/v1/files.
Użyj zwróconego id jako attachments[].file_id.

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

Plik musi należeć do tego samego konta, mieć kind: "image" i być dostępny. Modele, które nie obsługują załączników obrazów, zwracają chat_attachment_not_supported.

Opcjonalne Kontrole

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

Obsługa kontroli różni się w zależności od modelu. Przed pokazaniem tych kontroli w swoim UI odczytaj /api/v1/models i sprawdź chat_capabilities.

Lista Sesji

Użyj GET /api/v1/chat/sessions z kluczem zawierającym chat:read.

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

To zwraca tylko sesje utworzone przez API:

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

Pobierz Sesję

Użyj GET /api/v1/chat/sessions/{sessionId}, aby odczytać jedną sesję utworzoną przez API oraz jej zatwierdzone wiadomości.

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

Odpowiedź zawiera zatwierdzone wiadomości użytkownika i asystenta. Nie ujawnia wewnętrznych pól dostawcy.

Idempotencja

Używaj Idempotency-Key dla każdego produkcyjnego żądania POST /api/v1/chat/completions i POST /api/v1/chat/completions/stream.

Jeśli ponowienie używa tego samego klucza i tej samej treści żądania, Rivya może zwrócić zapisaną odpowiedź bez tworzenia kolejnej wiadomości ani ponownego zużywania kredytów. Jeśli ten sam klucz zostanie ponownie użyty z innymi danymi wejściowymi, API zwraca idempotency_conflict.

Przy ponowieniach streamingu Rivya nie odtwarza historycznych delt tokenów. Powtórzenie ukończonego żądania zwraca minimalną sekwencję SSE z session.created, message.completed, usage.completed i done.

Typowe Błędy

Code	Znaczenie
`chat_model_not_supported`	Wybrany model nie jest dostępny dla Chat API.
`chat_session_conflict`	Tej sesji nie można użyć dla tego żądania.
`chat_attachment_not_supported`	Brakuje załącznika, nie należy on do konta, nie jest obrazem albo model go nie obsługuje.
`insufficient_credits`	Konto nie ma wystarczającej liczby kredytów dla tej tury.
`idempotency_conflict`	Klucz idempotencji został ponownie użyty z innymi danymi wejściowymi.

Chat API