API для нейросетей в России: протокол, ключ и первый запрос

Перед подключением API для нейросетей выясните, какой контракт ждёт клиент: OpenAI-compatible или Anthropic-compatible. Затем возьмите Base URL из актуальной документации выбранного провайдера, храните API Key вне кода и выполните один короткий запрос. Сохранённая без ошибки форма настроек ещё не подтверждает подключение: проверьте HTTP status, модель в ответе, поля usage, если endpoint их возвращает, и запись об использовании у провайдера.

BetterToken — один из вариантов API-доступа с отдельными OpenAI-compatible и Anthropic-compatible интерфейсами. Используйте собственный аккаунт и API Key, а затем выполните минимальный вызов. При подключении к BetterToken API Endpoint из России VPN не требуется; это не относится к сайтам, аккаунтам и загрузкам сторонних инструментов.

API-доступ, веб-подписка и чужой аккаунт — не одно и то же

При API-доступе приложение отправляет HTTP-запрос к endpoint провайдера с вашим ключом. Веб-подписка даёт доступ к интерфейсу конкретного сервиса и не обязана включать тот же API-баланс или те же параметры подключения.

Не используйте в проекте чужой аккаунт или ключ как короткий путь. Это создаёт риск для безопасности и владения доступом. Работайте с аккаунтом и ключом, которые команда может отозвать и заменить, а затем следуйте документации выбранного провайдера.

Выберите протокол по контракту клиента

Откройте документацию SDK, CLI или приложения, которое будет отправлять запрос. Протокол определяет контракт клиента, а не маркетинговое название модели.

OpenAI-compatible конфигурация нужна, когда инструмент документирует OpenAI SDK, Chat Completions, Responses или поле вроде OPENAI_BASE_URL. Anthropic-compatible конфигурация нужна, когда инструмент формирует Messages-запросы и использует ANTHROPIC_BASE_URL или авторизацию через x-api-key.

OpenAI-compatible не означает, что каждый провайдер реализует все ресурсы OpenAI. Если инструмент ожидает Responses, используйте формат запроса Responses из документации этого провайдера, а не шаблон Chat Completions ниже. Аналогично, Anthropic-compatible инструменту нужен контракт Messages, а не Bearer token из OpenAI-примера.

Нужно сверить протокол и поля первого запроса? Открыть справочник по настройке API

Не путайте Base URL и полный путь запроса

Base URL — это корень, к которому SDK или готовый инструмент добавляет свой resource path. Для прямого curl-запроса нужен полный путь. Это разные значения.

У OpenAI-compatible провайдера Base URL и путь Chat Completions могут выглядеть так:

Base URL: https://api.example.com/v1
Полный путь: https://api.example.com/v1/chat/completions

У Anthropic-compatible провайдера схема может быть такой:

Base URL: https://api.example.com
Полный путь Messages: https://api.example.com/v1/messages

Это формы URL, а не готовые значения для вашей конфигурации. Реальные Base URL и полный path копируйте только из документации выбранного провайдера. Если поле называется Base URL, не добавляйте к нему /chat/completions или /v1/messages, пока документация инструмента прямо этого не требует. Иначе клиент может добавить путь второй раз и получить 404.

Храните API Key как secret

Для локальной проверки используйте переменные окружения с плейсхолдерами:

export API_KEY="your_api_key_here"
export MODEL_ID="your_current_model_id"
export OPENAI_BASE_URL="https://api.example.com/v1"
export ANTHROPIC_BASE_URL="https://api.example.com"

Не добавляйте настоящий ключ в исходный код, .env.example, issue, prompt, скриншот или shell-команду, которая останется в общей истории. В production используйте secret manager выбранной платформы. OpenAI-compatible и Anthropic-compatible параметры храните раздельно, чтобы правильный ключ не ушёл с неверным заголовком или URL.

Отправьте минимальный OpenAI-compatible запрос

Используйте этот шаблон только если выбранный провайдер документирует контракт Chat Completions. Base URL и Model ID здесь нужно заменить актуальными значениями этого провайдера.

curl "$OPENAI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$MODEL_ID"'",
    "messages": [{"role": "user", "content": "Reply with API_OK"}],
    "max_tokens": 16
  }'

Контракт OpenAI Chat Completions использует Bearer-авторизацию и ресурс /chat/completions. Не добавляйте -v в лог, доступный другим людям: verbose-вывод может раскрыть заголовки запроса.

Отправьте минимальный Anthropic-compatible запрос

Используйте этот шаблон, только когда выбранный провайдер документирует контракт Anthropic Messages. Заголовок ключа, заголовок версии и тело запроса отличаются от OpenAI-compatible примера.

curl "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "x-api-key: $API_KEY" \
  -H "anthropic-version: CURRENT_SUPPORTED_VERSION" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$MODEL_ID"'",
    "max_tokens": 16,
    "messages": [{"role": "user", "content": "Reply with API_OK"}]
  }'

CURRENT_SUPPORTED_VERSION намеренно оставлен плейсхолдером. Возьмите поддерживаемую версию и дополнительные headers из актуальной документации провайдера, к которому обращаетесь; не переносите значение из старой статьи.

Проверьте ответ, а не только экран настроек

Первый вызов можно считать успешным, когда совпали несколько признаков:

• HTTP status указывает на успех;
• в ответе указана ожидаемая Model ID или её документированное отображение;
• присутствует usage, если этот endpoint обещает такие поля;
• в записи провайдера об использовании или списании есть запрос с ожидаемыми статусом и стоимостью.

Доступность моделей, Model ID и цены меняются. Перед расчётом бюджета проверяйте текущий каталог и страницу цен провайдера. Не переносите цену, cache discount, совместимость или доступность с другой модели либо из старого руководства.

Диагностируйте первые ошибки

401

Проверьте ключ, лишние пробелы и способ авторизации. Bearer и x-api-key не взаимозаменяемы: используйте заголовок, который требует выбранный протокол.

404

Сравните Base URL инструмента с полным путем запроса. Двойной /v1 или повторный сегмент /chat/completions — частая ошибка конфигурации.

model not found

Скопируйте текущую Model ID у выбранного провайдера и убедитесь, что она доступна для ключа и протокола. Маркетинговое имя модели может отличаться от API ID. Если ошибка сохраняется, пройдите проверку model not found по слоям.

Timeout или TLS error

Сначала отделите локальную сеть, proxy и сертификаты от HTTP-ответа. Короткий прямой запрос помогает понять, доступен ли endpoint. Не отключайте проверку TLS как постоянное решение; используйте диагностику API timeout и безопасного retry.

Усложняйте workflow после первого успешного запроса

Практический порядок такой: определить контракт клиента, сохранить ключ как secret, указать корректный Base URL, отправить короткий запрос и проверить ответ с записью об использовании. Только затем включайте streaming, tools, длинный контекст или agent workflow. У каждого слоя свой формат событий и свои ошибки; если включить всё сразу, первую проблему будет сложнее локализовать.

Для OpenAI-compatible клиента сверьте актуальные параметры на странице OpenAI API BetterToken, а для Claude Code используйте отдельную инструкцию Anthropic-compatible подключения.

Источники

• OpenAI Chat Completions API reference
• Anthropic Messages API reference