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-статуса выбранной модели. Перед производственным запросом проверьте актуальный список моделей.

Текущая область

Chat API v1 поддерживает:

• непотоковые ответы ассистента

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

• сессии чата, созданные через API

• резервирование кредитов аккаунта и финальный расчет по использованию токенов

• необязательный поиск в интернете, глубина рассуждений и режим размышления, если выбранная модель их поддерживает

• вложения изображений через значения file_id из Files API

Chat API v1 не поддерживает:

• исходную историю messages, переданную пользователем

• продолжение Studio-only сессий чата

• произвольные внешние URL вложений

• события webhooks чата

Требуемые scope

Используйте API-ключ с:

chat:create
chat:read

Новые ключи, созданные в разделе «Настройки», по умолчанию включают обе области доступа. Старые ключи может потребоваться создать заново перед вызовом Chat API.

Создание завершения чата

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, когда вашему серверу нужны частичные ответы ассистента по мере появления:

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.

События:

Пример потока:

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, поток отправляет 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": "Теперь превратите его в список из пяти шагов."
  }'

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

Вложения изображений

Вложения Chat используют записи 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.

Опциональные элементы управления

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

Поддержка элементов управления различается по моделям. Прочитайте /api/v1/models и проверьте chat_capabilities, прежде чем показывать эти элементы в вашем 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": "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, и ее зафиксированные messages.

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

Ответ включает сохраненные сообщения пользователя и ассистента. Внутренние поля провайдера не раскрываются.

Идемпотентность

Используйте 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 и схема