Chat API

Використовуйте POST /api/v1/chat/completions для однієї повної відповіді без потокового передавання або POST /api/v1/chat/completions/stream для подій SSE.

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

Сторінка описує реалізований контракт Public API v1. Доступ під час виконання й надалі залежить від увімкненого Public API в розгортанні, активного API-ключа акаунта й доступного API-статусу обраної моделі. Перед виробничим запитом перевірте актуальний список моделей.

Поточний scope

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

• відповіді асистента без потокового передавання

• потокова передача SSE з text/event-stream

• сесії чату, створені через API

• резервування кредитів акаунта та фінальне списання на основі токенів

• необов’язковий пошук в інтернеті, глибину міркувань і режим роздумів, коли це підтримує вибрана модель

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

Відповідь:

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

Потокова відповідь чату

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

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

Події:

Приклад 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":"Чернетка ","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, потік надсилає event: error, а потім закривається:

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

Якщо клієнт від’єднується до завершення, Rivya за можливості зупиняє активний потік генерації. Часткові фрагменти не зберігаються як фінальне повідомлення асистента. Якщо сервер уже зафіксував 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": "claude-sonnet-5-chat",
    "session_id": "session_id",
    "message": "Тепер перетвори це на чеклист виконання з 5 кроків."
  }'

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

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

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

1. Завантажте зображення через POST /api/v1/files.

2. Використовуйте повернений id як attachments[].file_id.

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

Файл має належати тому самому акаунту, мати kind: "image" і бути доступним. Замініть заповнювач доступною зараз чат-моделлю, запис якої в /api/v1/models повідомляє підтримку зображень у chat_capabilities. Використана в інших прикладах claude-sonnet-5-chat є текстовою моделлю й для цього запиту не підходить. Моделі без підтримки зображень повертають chat_attachment_not_supported.

Опційні controls

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

Підтримка елементів керування залежить від моделі. Прочитайте /api/v1/models і перевірте chat_capabilities, перш ніж показувати їх у своєму інтерфейсі.

Список сесій

Використовуйте 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": "claude-sonnet-5-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 для кожного робочого запиту POST /api/v1/chat/completions і POST /api/v1/chat/completions/stream.

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

Під час повторних потокових запитів Rivya не відтворює попередні фрагменти токенів. Повтор завершеного запиту повертає мінімальну послідовність SSE із session.created, message.completed, usage.completed і done.

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

Пов'язані сторінки

• API-моделі

• Files API

• API кредити

• Помилки та ліміти API

• OpenAPI та контракт схеми