Справочник API
Базовые URL, заголовки аутентификации, заголовки ответов, лимиты запросов и правила повторов для вызова Claude, GPT и Gemini через родные API Half Off Dev.
Half Off Dev не изобретает новый API. Он предоставляет три, на которых уже говорят ваш код и SDK, — Anthropic Messages, OpenAI Chat Completions (и Responses) и Gemini — с одного хоста, с одним ключом и одним предоплаченным балансом. Тела запросов и ответов передаются в схеме каждого вендора, так что официальным SDK нужен лишь новый базовый URL и ключ. Half Off Dev добавляет немного: несколько заголовков ответа, лимиты на уровне ключей и собственную тарификацию.
Форматы всех запросов и ответов с примерами на cURL, Python и Node.js.
Коды статуса, тела ошибок в каждом формате и рецепт повторов.
Куда помещать ключ для каждого SDK.
Ваш первый запрос за полцены.
Базовые URL#
Всё обслуживается по HTTPS с https://halfoff.dev. Задайте в SDK базовый URL из второго столбца.
| API | Базовый URL SDK | Эндпоинты |
|---|---|---|
| Anthropic Messages | https://halfoff.dev | POST /v1/messages, POST /v1/messages/count_tokens |
| OpenAI Chat Completions | https://halfoff.dev/v1 | POST /v1/chat/completions |
| OpenAI Responses (модели GPT) | https://halfoff.dev/v1 | POST /v1/responses |
| Gemini | https://halfoff.dev | POST /v1beta/models/{model}:generateContent, :streamGenerateContent, :countTokens |
| Список моделей | — | GET /v1/models, GET /v1beta/models |
Любой другой путь, например OpenAI Embeddings API, отвечает 404.
Аутентификация#
На каждом эндпоинте работает bearer-токен. Заголовок каждого вендора тоже подходит, так что любой SDK может сохранить настройки по умолчанию.
Authorization: Bearer ho-...| Заголовок | Кто отправляет |
|---|---|
Authorization: Bearer ho-... | OpenAI SDK, обычные HTTP-клиенты |
x-api-key: ho-... | Anthropic SDK |
x-goog-api-key: ho-... | Google Gen AI SDK |
Список моделей публичный. Любому другому эндпоинту нужен ключ. Подробности в разделе Аутентификация.
Формат запросов и ответов#
- JSON в обе стороны. Отправляйте тела в формате JSON с
content-type: application/json; ответы тоже в JSON. - Потоковая передача. Запросы Anthropic и OpenAI с
"stream": trueотвечают серверными событиями (text/event-stream).:streamGenerateContentв Gemini возвращает потоковый JSON-массив или серверные события, если добавить?alt=sse, в точности как API Google. См. Потоковая передача. - CORS открыт для любых origin. Это не делает вызовы из браузера хорошей идеей: ключ во фронтенд-коде может скопировать кто угодно.
Заголовки ответа#
Помимо собственных заголовков вендора, ответы моделей содержат:
| Заголовок | Значение |
|---|---|
x-halfoff-request-id | Уникальный id вызова, отображается в Логах. Назовите его поддержке. |
x-halfoff-group | Группа каналов, обслужившая вызов |
x-halfoff-channel | Короткая URL-кодированная метка этой группы каналов |
x-halfoff-queued-ms | Сколько вызов ждал ёмкости, в миллисекундах (только если ждал) |
retry-after | При 429: сколько секунд подождать перед повтором |
Версионирование#
Каждый API сохраняет собственное версионирование вендора. Отправляйте то, что отправляет ваш SDK: anthropic-version и anthropic-beta для Anthropic, openai-beta для OpenAI; Gemini использует путь /v1beta, как и API Google. Half Off Dev пересылает эти заголовки и никакие другие заголовки вендоров, поэтому функция, зависящая от какого-то другого заголовка вендора, будет недоступна.
Со временем в ответах могут появляться новые поля. Пишите клиенты так, чтобы они пропускали незнакомые поля.
Лимиты запросов#
| Лимит | К чему применяется | Если превысить |
|---|---|---|
| Запросы в минуту и параллелизм, заданные для ключа | Запросы, сделанные с этим ключом | 429 с retry-after |
| Ёмкость модели | Все запросы к моделям. Короткий всплеск сначала несколько секунд ждёт в очереди. | 429, обычно с retry-after |
Подробнее в разделах Лимиты запросов и переключение и API-ключи.
Повторы и идемпотентность#
Когда канал отказывает, Half Off Dev пробует запрос на других каналах, прежде чем сдаться, так что дошедшая до вас ошибка 5xx уже была повторена. И всё же повторяйте 429 и 5xx на своей стороне с экспоненциальной задержкой и учитывайте retry-after. Остальные ошибки 4xx требуют изменить запрос, а не повторять его. Официальные SDK Anthropic и OpenAI по умолчанию повторяют дважды; для долгих пакетных задач увеличьте max_retries (maxRetries в Node.js).
Ключей идемпотентности нет, и это важно в одном случае: запрос, у которого истёк таймаут на вашей стороне, мог завершиться и всё равно быть оплаченным. Его повтор может означать двойную оплату. Задавайте для долгих генераций щедрый клиентский таймаут или используйте потоковую передачу. Получение списка моделей и подсчёт токенов всегда безопасно повторять.
Готовые помощники для повторов есть в разделе Ошибки.
Ошибки#
Ошибки возвращаются в формате вызванного вами эндпоинта, поэтому каждый SDK выбрасывает привычное для него исключение. Например, запрос в формате OpenAI с отозванным ключом получит:
{"error": {"message": "Invalid or revoked API key", "type": "authentication_error", "code": "authentication_error"}}Все коды статуса с примерами тел во всех форматах перечислены в разделе Ошибки.