Справочник API: два семейства форматов и batch на одном ключе
Как читать справочник
Методы описаны в OpenAPI-спеке (версия 1.1.0 от 2026-10-26). У каждого метода: запрос curl, ответ целиком, таблица полей и таблица ошибок „код → причина → действие“. Работали с SDK OpenAI или Anthropic — формат знаком: пути, имена полей и стриминг совпадают с вендорскими.
OpenAPI-спека 3.1 — машиночитаемый источник (YAML)
Соответствие форматов
| Семейство | Endpoint'ы | Авторизация | Стриминг | Batch |
|---|---|---|---|---|
| OpenAI | POST /v1/chat/completions, /v1/embeddings, /v1/images/generations, /v1/audio/speech, /v1/audio/transcriptions; GET /v1/models | Authorization: Bearer <key> | SSE-чанки choices | POST /v1/batches + загрузка файла POST /v1/files |
| Anthropic Messages | POST /v1/messages | x-api-key: <key> + anthropic-version: 2023-06-01; anthropic-beta — pass-through | SSE: message_start → content_block_start → content_block_delta → content_block_stop → message_delta → message_stop | POST /v1/messages/batches, requests inline |
Drop-in подключение
Drop-in подключение: меняются base_url и ключ. OpenAI-клиент: base https://api.farvater.copul4.com/v1. Anthropic-клиент: base https://api.farvater.copul4.com без /v1 — клиент сам добавляет путь. Ключ один: ruslo-sk-…
- base_url="https://api.openai.com/v1"
+ base_url="https://api.farvater.copul4.com/v1"Для anthropic-SDK так же: base меняется на https://api.farvater.copul4.com.
ваш код на OpenAI SDK или Anthropic SDK заработает без переписывания — поменяйте base_url и ключ.
Добавлено поверх форматов
Добавлено поверх форматов: usage.cost_rub и usage.balance_rub в ответах OpenAI; заголовки обоих семейств Ruslo-Usage-Cost (цена запроса в копейках) и Ruslo-Usage-Path (маршрут), Ruslo-Request-Id, Ruslo-RateLimit-Remaining и Ruslo-RateLimit-Limit.
Конверт ошибок Anthropic
{"type":"error","error":{"type":"invalid_request_error|authentication_error|rate_limit_error|overloaded_error|api_error","message":…}}при HTTP 400/401/429/500/529.
Ошибки и ретраи
429 и 5xx допускается повторять: exponential backoff 1с → 2с → 4с, не более трёх повторов. 503 upstream_unavailable повторять безопасно: погибший запрос не тарифицирован. 4xx кроме 429 повторять бессмысленно: причина в теле ошибки.
| Код | Причина | Действие |
|---|---|---|
| 401 invalid_api_key / authentication_error | ключ отозван или неверен | сверьте префикс ruslo-sk-; при утере отзовите и создайте новый (K1) |
| 400 model_not_found | идентификатор вне каталога или deprecated | возьмите id из D2 как есть |
| 400 invalid_request_error | Anthropic: нет заголовка anthropic-version или нарушена схема тела | добавьте заголовок; проверьте max_tokens и messages |
| 402 payment_required / insufficient_balance | баланс ниже цены запроса или грант исчерпан | пополните от 500 ₽; автосписаний нет (D4) |
| 429 rate_limit_exceeded / rate_limit_error | превышен RPM/TPM ключа | снизьте параллельность или поднимите лимит в K3 |
| 503 upstream_unavailable / overloaded_error | вендор недоступен, резерв не подхватил | повтор с backoff; запрос не тарифицирован |
Batch и тарификация
Batch-endpoint'ы обоих семейств: create / list / get / cancel / results — схемы и JSONL в D6 (Batch-гайд в docs); тарификация — D4 (Цены и биллинг в доках).
Лимиты
По умолчанию на ключ: RPM 60, TPM 150 000, независимо от семейства формата. Текущие значения и остаток — в заголовках ответа Ruslo-RateLimit-Remaining и Ruslo-RateLimit-Limit.
Логи и персональные данные
Тела запросов и ответов по умолчанию не хранятся: только транзит. Журналируются метаданные — ключ, модель, семейство формата, токены и единицы, ₽, время, маршрут — для биллинга и аудита. Маскирование полей с ПДн в теле запроса доступно на enterprise-тарифе списком полей; схема — в опроснике безопасности (M5).
Обновлено: 2026-10-26