rovex.host
ВойтиНачать бесплатноНачать

Документация API

Единый OpenAI-совместимый API для GPT, Claude и других моделей. Один endpoint, один ключ и единый баланс для всех подключений.

Совместимо с привычными инструментами

Подключите официальный OpenAI SDK, Claude Code, Cursor, Cline, Continue или отправляйте обычные HTTP-запросы. Меняются только адрес API, ключ и модель.

01

Быстрый старт

Чтобы отправить первый запрос, достаточно аккаунта с положительным балансом и активного API-ключа.

  1. Создайте аккаунт на странице регистрации и войдите в консоль.
  2. Откройте API-ключи, нажмите «Создать ключ» и сохраните секрет. Полный ключ показывается только один раз.
  3. Пополните баланс минимум на $1 в разделе «Кошелёк».
  4. Выберите alias модели в каталоге моделей.
  5. Отправьте запрос на POST /v1/chat/completions.
POST/v1/chat/completionsчат и генерация текста
cURL · самый короткий рабочий пример
curl https://api.rovex.host/v1/chat/completions \
  -H "Authorization: Bearer $ROVEX_HOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5",
    "messages": [
      {"role": "user", "content": "Привет!"}
    ]
  }'
Что должно вернуться
В успешном ответе будут choices[0].message.content, выбранная модель и объект usage с количеством токенов.
02

Авторизация

Каждый запрос к публичному API должен содержать API-ключ. Используйте один из двух эквивалентных вариантов.

Bearer-токен

Рекомендуемый вариант
Authorization: Bearer ROVEX_HOST_API_KEY

Заголовок x-api-key

Альтернативный вариант
x-api-key: ROVEX_HOST_API_KEY

Ключи привязаны к организации и проекту. Если ключ отключён, удалён, истёк или ему запрещена выбранная модель, API вернёт ошибку до отправки запроса провайдеру.

Никогда не публикуйте секрет
Храните ключ в переменной окружения или секрет-хранилище. Не вставляйте его в браузерный код, Git, скриншоты и публичные логи.
03

Первый запрос

Тело запроса использует формат Chat Completions. Минимально необходимы только model и массив messages.

JavaScript · fetch
const response = await fetch("https://api.rovex.host/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.ROVEX_HOST_API_KEY,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "gpt-5",
    messages: [
      { role: "system", content: "Отвечай кратко." },
      { role: "user", content: "Что такое API?" }
    ],
    temperature: 0.2,
    max_tokens: 256
  })
});

const data = await response.json();
console.log(data.choices[0].message.content);
Python · requests
import os
import requests

response = requests.post(
    "https://api.rovex.host/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {os.environ["ROVEX_HOST_API_KEY"]}",
        "Content-Type": "application/json",
    },
    json={
        "model": "gpt-5",
        "messages": [{"role": "user", "content": "Привет!"}],
    },
    timeout=60,
)
response.raise_for_status()
print(response.json()["choices"][0]["message"]["content"])
04

Доступные endpoint-ы

Все публичные маршруты работают на домене api.rovex.host. Для OpenAI-совместимых запросов используйте префикс /v1.

POST/v1/chat/completionsOpenAI-совместимый чат
POST/v1/messagesAnthropic-совместимые сообщения
GET/v1/modelsдоступные alias моделей
POST/v1/embeddingsвекторные представления
GET/healthготовность API, базы и Redis

Endpoint /v1/messages принимает общий формат входных данных, но возвращает Anthropic-совместимый ответ. Для прямого HTTP-запроса используйте полный адрес https://api.rovex.host/v1/messages.

Что пока не включено
/v1/responses, /v1/rerank и /v1/messages/count_tokens возвращают 501 CAPABILITY_NOT_ENABLED, пока совместимость этих режимов не прошла проверку.
05

Параметры запроса

Ниже перечислены поддерживаемые поля. Неизвестные поля отклоняются, поэтому ошибки конфигурации видны сразу.

ПолеТипОписание
modelstringAlias из каталога моделей.
messagesarrayОт 1 до 200 сообщений с ролями system, user, assistant или tool.
systemstring / arrayСистемная инструкция. Удобна для Anthropic-совместимого режима.
streambooleanОтдавать ответ частями через SSE. По умолчанию false.
max_tokensintegerМаксимум выходных токенов.
max_completion_tokensintegerАльтернативное имя лимита выходных токенов.
temperaturenumberСлучайность ответа от 0 до 2.
top_pnumberNucleus sampling от 0 до 1.
stopstring / arrayПоследовательности, на которых генерация останавливается.
stop_sequencesarrayAnthropic-совместимое имя stop, до 16 значений.
metadataobjectСтроковые метаданные запроса для вашей аналитики.
toolsarrayFunction calling или Anthropic tool-use, до 32 инструментов.
stream_optionsobjectinclude_usage: true добавляет usage в финальный chunk.
Ограничения совместимости
response_format и tool_choice сейчас не включены и вернут 400 UNSUPPORTED_PARAMETER. JSON-режим не следует имитировать через эти поля.
06

Формат ответа

Для OpenAI-режима ответ содержит массив choices. Количество токенов находится в usage, если провайдер сообщил его до завершения операции.

Успешный ответ · OpenAI
{
  "id": "request-id",
  "object": "chat.completion",
  "created": 1760000000,
  "model": "gpt-5",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "Привет! Чем помочь?"
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 12,
    "total_tokens": 36
  }
}

В Anthropic-режиме ответ содержит content, stop_reason и usage-поля input_tokens, output_tokens, cache_read_input_tokens и cache_creation_input_tokens.

Успешный ответ · Anthropic
{
  "id": "request-id",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-4",
  "content": [{"type": "text", "text": "Привет! Чем помочь?"}],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 24,
    "output_tokens": 12
  },
  "usage_status": "reported"
}

Заголовок x-request-id помогает найти запрос в журнале активности. При повторе успешной идемпотентной операции появится idempotency-replayed: true.

07

SDK и интеграции

Для GPT и других OpenAI-совместимых моделей используйте стандартные SDK. Укажите базовый URL https://api.rovex.host/v1.

OpenAI SDK · JavaScript / TypeScript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.ROVEX_HOST_API_KEY,
  baseURL: "https://api.rovex.host/v1"
});

const result = await client.chat.completions.create({
  model: "gpt-5",
  messages: [{ role: "user", content: "Привет!" }]
});

console.log(result.choices[0].message.content);
OpenAI SDK · Python
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["ROVEX_HOST_API_KEY"],
    base_url="https://api.rovex.host/v1",
)

result = client.chat.completions.create(
    model="gpt-5",
    messages=[{"role": "user", "content": "Привет!"}],
)
print(result.choices[0].message.content)

Для Claude Code и Anthropic SDK используйте нативный маршрут /v1/messages. Пошаговые настройки Cursor, Cline, Continue, Codex и других инструментов находятся в разделе «Гайды».

08

Модели и каталог

Модель выбирается по alias, а не по отображаемому названию. Получить список разрешённых для ключа моделей можно без отдельного запроса к консоли.

GET/v1/modelsсписок доступных alias
Получить каталог
curl https://api.rovex.host/v1/models \
  -H "Authorization: Bearer $ROVEX_HOST_API_KEY"
Пример ответа
{
  "object": "list",
  "data": [{
    "id": "gpt-5",
    "object": "model",
    "owned_by": "rovex.host",
    "capabilities": {
      "tools": true,
      "vision": false,
      "reasoning": true
    }
  }]
}

Если API-ключ ограничен списком моделей, запрос к alias вне этого списка завершится ошибкой 403 MODEL_SCOPE. Актуальные цены и доступность смотрите в каталоге моделей.

09

Claude и Anthropic API

Для Claude можно использовать Anthropic-совместимый формат. Тело запроса содержит model, max_tokens, messages и необязательный system.

cURL · POST /v1/messages
curl https://api.rovex.host/v1/messages \
  -H "x-api-key: $ROVEX_HOST_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4",
    "max_tokens": 512,
    "system": "Отвечай на русском языке.",
    "messages": [
      {"role": "user", "content": "Объясни, что такое API."}
    ]
  }'
Python · Anthropic SDK
import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["ROVEX_HOST_API_KEY"],
    base_url="https://api.rovex.host",
)

message = client.messages.create(
    model="claude-sonnet-4",
    max_tokens=512,
    messages=[{"role": "user", "content": "Привет!"}],
)
print(message.content[0].text)
Адрес для Anthropic SDK
В нативном Anthropic SDK укажите base URL без /v1: SDK сам добавит /v1/messages. В прямом HTTP-запросе используйте полный путь.
10

Изображения и tools

Vision работает через base64. Внешние HTTP-ссылки на изображения не принимаются. Изображения разрешены только в сообщениях роли user.

OpenAI-совместимое изображение
{
  "model": "gpt-5",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "Что изображено на картинке?"},
      {
        "type": "image_url",
        "image_url": {
          "url": "data:image/png;base64,BASE64_DATA"
        }
      }
    ]
  }]
}

Инструменты передаются как функции с JSON Schema. Поддержка зависит от capabilities выбранной модели.

Function calling
{
  "model": "gpt-5",
  "messages": [{"role": "user", "content": "Какая погода в Москве?"}],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Получить текущую погоду",
      "parameters": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"]
      }
    }
  }]
}
Важно для изображений
Максимум одного изображения — 5 MiB, суммарно в запросе — 6 MiB. Поддерживаются PNG, JPEG, WebP и GIF.
11

Потоковая генерация

Передайте stream: true, чтобы получать ответ частями через Server-Sent Events. Поток нельзя воспроизвести после начала выдачи; при разрыве создайте новый запрос.

JavaScript · чтение OpenAI SSE
const stream = await client.chat.completions.create({
  model: "gpt-5",
  messages,
  stream: true,
  stream_options: { include_usage: true }
});

for await (const chunk of stream) {
  const text = chunk.choices[0]?.delta?.content;
  if (text) process.stdout.write(text);
}
Фрагмент SSE-ответа
data: {"object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Привет"}}]}

data: {"object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"!"}}]}

data: [DONE]

Для Anthropic поток использует события content_block_delta. Если провайдер не сообщил usage, операция отмечается как unknown и может потребовать проверки в журнале расчётов.

12

Ошибки и повторные попытки

Ошибка всегда возвращается в едином объекте error. Поле request_id используйте при обращении в поддержку.

Формат ошибки
{
  "error": {
    "type": "gateway_error",
    "code": "MODEL_NOT_FOUND",
    "message": "Model alias is unavailable.",
    "request_id": "00000000-0000-4000-8000-000000000001"
  }
}
КодПричинаЧто делать
400Некорректный запрос или неподдерживаемый параметрПроверьте JSON, модель и список параметров.
401Неверный или отсутствующий API-ключПроверьте Bearer или x-api-key и статус ключа.
402Недостаточно доступного балансаПополните баланс и повторите запрос.
403Модель не разрешена ключу или организацииВыберите alias из каталога или обновите scope ключа.
404Alias модели недоступенПроверьте точное имя в /v1/models.
409Конфликт Idempotency-KeyИспользуйте тот же body для повтора или новый ключ операции.
413Слишком большой payloadУменьшите изображения или текст.
429Rate, concurrency или spend limitСнизьте частоту, добавьте backoff и проверьте лимиты.
5xxОшибка провайдера или сервисаПовторите с exponential backoff и проверьте статус.
13

Лимиты и идемпотентность

Лимиты защищают баланс и стабильность маршрутизации. Они могут дополнительно ограничиваться политикой организации или API-ключа.

РесурсЛимит
Сообщения в одном запроседо 200
Инструменты в одном запроседо 32
Текст одной частидо 200 000 символов
Изображениедо 5 MiB каждое
Изображения суммарнодо 6 MiB на запрос
Idempotency-Keyот 8 до 200 символов
Embeddings inputдо 128 строк, до 200 000 символов каждая

Для безопасного повтора долгих запросов передавайте уникальный заголовок Idempotency-Key длиной от 8 символов. Успешный буферизованный ответ будет возвращён повторно без второго списания. Изменение тела с тем же ключом вернёт 409.

Идемпотентный запрос
curl https://api.rovex.host/v1/chat/completions \
  -H "Authorization: Bearer $ROVEX_HOST_API_KEY" \
  -H "Idempotency-Key: chat-order-2026-0001" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5","messages":[{"role":"user","content":"Привет!"}]}'
14

Баланс, кэш и расходы

Перед выполнением сервис резервирует максимальную возможную стоимость, а после ответа списывает фактическое использование. Неиспользованный резерв возвращается.

  • Стоимость зависит от модели и входных/выходных токенов.
  • Кэшированные входные токены учитываются отдельно и получают скидку.
  • В журнале консоли доступны вход, выход, кэш, итоговые токены и стоимость.
  • При неизвестном usage операция остаётся на проверке, а не списывается повторно.
  • Минимальная сумма пополнения — $1.
Пример usage с кэшем
"usage": {
  "prompt_tokens": 67738,
  "completion_tokens": 389,
  "total_tokens": 68127,
  "cache_read_input_tokens": 56448,
  "cache_creation_input_tokens": 0
}
Где смотреть расход
Откройте в консоли «Обзор» для сводки, «Журнал активности» для каждой операции и «Кошелёк» для пополнений и списаний.
Готовы начать?

Создайте аккаунт, выпустите API-ключ и подключите приложение.

Начать работу →