Використовуйте Rivya Chat API для non-streaming або SSE turn, сесій, створених через API, вкладень зображень file_id і кредитного списання на основі токенів.

Використовуйте POST /api/v1/chat/completions для однієї повної non-streaming відповіді чату або POST /api/v1/chat/completions/stream для Server-Sent Events.

Chat API працює на основі сесій. Не передавайте session_id, щоб почати нову API-сесію чату. Передайте повернений session_id, щоб продовжити ту саму сесію, створену через API.

Поточний scope

Chat API v1 підтримує:

non-streaming відповіді асистента
SSE streaming із text/event-stream
сесії чату, створені через API
резервування кредитів акаунта та фінальне списання на основі токенів
опційний web search, reasoning effort і thought mode, коли це підтримує вибрана модель
вкладення зображень через значення Files API file_id

Chat API v1 не підтримує:

передану користувачем сиру історію messages
продовження сесій чату лише зі Studio
довільні зовнішні URL вкладень
події chat webhook

Потрібні scopes

Використовуйте API-ключ із:

chat:create
chat:read

Нові ключі, створені в Settings, за замовчуванням містять обидва scopes. Старіші ключі може знадобитися створити заново перед викликом Chat API.

Створення 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": "Напиши стислий план запуску для нової кампанії з продуктовими зображеннями",
    "client_request_id": "chat-001"
  }'

Відповідь:

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

Streaming chat completion

Використовуйте POST /api/v1/chat/completions/stream, коли вашому серверу потрібні deltas асистента одразу після появи:

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": "Напиши стислий план запуску для нової кампанії з продуктовими зображеннями",
    "client_request_id": "chat-stream-001"
  }'

Streaming responses використовують Content-Type: text/event-stream; charset=utf-8.

Події:

Подія	Значення
`session.created`	API-ключ, модель, сесія, вкладення, rate limit і перевірки резервування кредитів пройшли успішно.
`message.delta`	Display delta для повідомлення асистента. Це ще не зафіксоване повідомлення.
`message.completed`	Повідомлення асистента зафіксовано в сесії, створеній через API.
`usage.completed`	Використання токенів і фінальні кредити списано.
`heartbeat`	Keepalive-подія під час довгих пауз.
`error`	Public API error envelope для помилки після старту streaming.
`done`	Stream успішно завершився.

Приклад 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":"Чернетка ","index":0}

event: message.completed
data: {"request_id":"req_...","session_id":"session_id","message":{"id":"assistant_message_id","role":"assistant","content":"Чернетка ...","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}

Якщо помилка стається після першої SSE-події, stream надсилає event: error, а потім закривається:

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

Якщо клієнт від'єднується до завершення, Rivya зупиняє активний generation stream, коли це можливо. Часткові deltas не зберігаються як фінальне повідомлення асистента. Якщо сервер уже зафіксував message.completed, фінальний результат можна пізніше прочитати через GET /api/v1/chat/sessions/{sessionId}.

Продовження сесії

Використовуйте повернений 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": "Тепер перетвори це на чеклист виконання з 5 кроків."
  }'

Сесія має належати тому самому акаунту Rivya і має бути створена Public API. Сесії чату лише зі Studio не повертаються і не продовжуються Chat API.

Вкладення зображень

Вкладення чату використовують записи Files API, а не зовнішні URL.

Завантажте зображення через POST /api/v1/files.
Використовуйте повернений id як attachments[].file_id.

{
  "model": "gpt-5-2-chat",
  "message": "Переглянь це продуктове фото й запропонуй чистіший редакційний напрям.",
  "attachments": [
    {
      "file_id": "file_..."
    }
  ]
}

Файл має належати тому самому акаунту, мати kind: "image" і бути доступним. Моделі, що не підтримують вкладення зображень, повертають chat_attachment_not_supported.

Опційні controls

{
  "model": "gpt-5-2-chat",
  "message": "Порівняй три варіанти запуску.",
  "enable_web_search": false,
  "reasoning_effort": "default",
  "thought_mode": "default"
}

Підтримка controls залежить від моделі. Прочитайте /api/v1/models і перевірте chat_capabilities, перш ніж показувати controls у вашому UI.

Список сесій

Використовуйте GET /api/v1/chat/sessions з ключем, який містить chat:read.

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

Це повертає лише сесії, створені через API:

{
  "object": "list",
  "data": [
    {
      "id": "session_id",
      "object": "chat.session",
      "model": "gpt-5-2-chat",
      "tool_slug": null,
      "title": "Напиши стислий план запуску...",
      "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"
    }
  ]
}

Отримання сесії

Використовуйте GET /api/v1/chat/sessions/{sessionId}, щоб прочитати одну сесію, створену через API, та її зафіксовані повідомлення.

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

Відповідь містить зафіксовані повідомлення користувача та асистента. Вона не відкриває внутрішні поля provider.

Idempotency

Використовуйте Idempotency-Key для кожного production-запиту POST /api/v1/chat/completions і POST /api/v1/chat/completions/stream.

Якщо retry використовує той самий ключ і те саме тіло, Rivya може повернути збережену відповідь без створення ще одного повідомлення або повторного споживання кредитів. Якщо той самий ключ повторно використано з іншим input, API повертає idempotency_conflict.

Для streaming retries Rivya не відтворює історичні token deltas. Завершений replay повертає мінімальну SSE-послідовність із session.created, message.completed, usage.completed і done.

Поширені помилки

Code	Значення
`chat_model_not_supported`	Вибрана модель недоступна для Chat API.
`chat_session_conflict`	Сесію не можна використати для цього запиту.
`chat_attachment_not_supported`	Вкладення відсутнє, не належить акаунту, не є зображенням або не підтримується моделлю.
`insufficient_credits`	В акаунті недостатньо кредитів для turn.
`idempotency_conflict`	Idempotency key повторно використано з іншим input.

Chat API