Chat API

Используйте POST /api/v1/chat/completions для одного полного непотокового ответа чата или POST /api/v1/chat/completions/stream для Server-Sent Events.

Chat API основан на сессиях. Опустите session_id, чтобы начать новую сессию чата API. Передайте возвращенный session_id, чтобы продолжить ту же сессию, созданную через API.

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

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

• непотоковые ответы ассистента
• SSE streaming с text/event-stream
• сессии чата, созданные через API
• резервирование кредитов аккаунта и финальный расчет по использованию токенов
• опциональный поиск в интернете, reasoning effort и thought mode, если выбранная модель их поддерживает
• вложения изображений через значения file_id из Files API

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

• raw history messages, переданную пользователем
• продолжение Studio-only сессий чата
• произвольные внешние URL вложений
• события webhooks чата

Требуемые scope

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

chat:create
chat:read

Новые ключи, созданные в Settings, по умолчанию включают оба scope. Более старые ключи может потребоваться создать заново перед вызовом 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": "gpt-5-2-chat",
    "message": "Write a concise launch plan for a new product image campaign",
    "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
  }
}

Потоковое завершение чата

Используйте 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": "gpt-5-2-chat",
    "message": "Write a concise launch plan for a new product image campaign",
    "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":"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}

Если ошибка происходит после первого 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": "gpt-5-2-chat",
    "session_id": "session_id",
    "message": "Now turn that into a 5-step execution checklist."
  }'

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

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

Вложения Chat используют записи Files API, а не внешние URL.

1. Загрузите изображение через POST /api/v1/files.
2. Используйте возвращенный id как attachments[].file_id.

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

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

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

{
  "model": "gpt-5-2-chat",
  "message": "Compare three launch options.",
  "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_..."

Этот endpoint возвращает только сессии, созданные через 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"
    }
  ]
}

Получение сессии

Используйте GET /api/v1/chat/sessions/{sessionId}, чтобы прочитать одну сессию, созданную через API, и ее зафиксированные messages.

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

Ответ включает зафиксированные сообщения user и assistant. Он не раскрывает внутренние поля provider.

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

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

Если повторная попытка использует тот же key и то же body, Rivya может вернуть сохраненный ответ без создания еще одного message и без повторного расхода кредитов. Если тот же key повторно используется с другим input, API возвращает idempotency_conflict.

Для потоковых повторов Rivya не воспроизводит исторические фрагменты токенов. Завершенное повторное воспроизведение возвращает минимальную SSE-последовательность с session.created, message.completed, usage.completed и done.

Распространенные ошибки

Связанные страницы

• Модели API
• Files API
• Кредиты API
• Ошибки и лимиты API
• Контракт OpenAPI и схема