Chat API

Użyj POST /api/v1/chat/completions, aby uzyskać jedną pełną odpowiedź czatu, albo POST /api/v1/chat/completions/stream, aby odbierać 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.

Strona opisuje wdrożony kontrakt Public API v1. Dostęp w czasie działania nadal zależy od włączenia Public API we wdrożeniu, aktywnego klucza API konta i dostępnego statusu API wybranego modelu. Przed żądaniem produkcyjnym sprawdź bieżącą listę modeli.

Bieżący Zakres

Chat API v1 obsługuje:

• pełne odpowiedzi asystenta bez strumienia

• strumień 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 Ustawieniach 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": "claude-sonnet-5-chat",
    "message": "Napisz zwięzły plan uruchomienia nowej kampanii obrazów produktowych",
    "client_request_id": "chat-001"
  }'

Odpowiedź:

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

Przesyłaj odpowiedź czatu strumieniowo

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": "claude-sonnet-5-chat",
    "message": "Napisz zwięzły plan uruchomienia nowej kampanii obrazów produktowych",
    "client_request_id": "chat-stream-001"
  }'

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

Zdarzenia:

Przykładowy strumień:

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":"Szkic ","index":0}

event: message.completed
data: {"request_id":"req_...","session_id":"session_id","message":{"id":"assistant_message_id","role":"assistant","content":"Szkic ...","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": "claude-sonnet-5-chat",
    "session_id": "session_id",
    "message": "Teraz zmień go w pięciopunktową listę działań."
  }'

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.

1. Prześlij obraz przez POST /api/v1/files.

2. Użyj zwróconego id jako attachments[].file_id.

{
  "model": "<image-capable-chat-model-id>",
  "message": "Oceń to zdjęcie produktu i zaproponuj czystszy kierunek redakcyjny.",
  "attachments": [
    {
      "file_id": "file_..."
    }
  ]
}

Plik musi należeć do tego samego konta, mieć kind: "image" i być dostępny. Zastąp placeholder aktualnie dostępnym modelem czatu, którego wpis /api/v1/models zgłasza obsługę obrazów w chat_capabilities. Używany w innych przykładach claude-sonnet-5-chat jest modelem tekstowym i nie nadaje się do tego żądania. Modele bez obsługi obrazów zwracają chat_attachment_not_supported.

Opcjonalne Kontrole

{
  "model": "claude-sonnet-5-chat",
  "message": "Porównaj trzy warianty wprowadzenia produktu.",
  "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": "claude-sonnet-5-chat",
      "tool_slug": null,
      "title": "Napisz zwięzły plan uruchomienia...",
      "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 ponawianiu żądania strumieniowego Rivya nie odtwarza wcześniejszych fragmentów tokenów. Powtórzenie ukończonego żądania zwraca minimalną sekwencję SSE z session.created, message.completed, usage.completed i done.

Typowe Błędy

Powiązane Strony

• Modele API

• Files API

• Kredyty API

• Błędy i limity API

• Kontrakt OpenAPI i schemat