OpenAI-совместимый API: подключаем клиенты, ботов и редакторы кода

Чем больше инструментов появляется в рабочем процессе, тем сложнее следить за доступами. Один ключ нужен редактору кода, другой — боту, третий — сценарию автоматизации. Для каждой модели приходится держать отдельную настройку и разбираться с форматом запросов.

OpenAI-совместимый шлюз упрощает эту схему. Клиент продолжает работать с привычным форматом API, но запросы отправляются на другой base_url. В конфигурации остаются три главных параметра: адрес шлюза, ключ и поле model.

NeuroZal API предоставляет единый шлюз к моделям OpenAI, Anthropic, Google, xAI, DeepSeek, Moonshot, Zhipu и Alibaba. Один ключ вида sk-nz-... открывает весь каталог, а нужную модель пользователь выбирает в каждом запросе.

Как работает OpenAI-совместимый шлюз

Обычный клиент OpenAI отправляет запросы на заранее заданный адрес. Большинство библиотек и часть пользовательских программ позволяют заменить этот адрес через параметр base_url.

Для NeuroZal API используется:

https://api.neurozal.ru/v1

После замены адреса схема выглядит так:

клиент или программа
        ↓
OpenAI-совместимый запрос
        ↓
https://api.neurozal.ru/v1
        ↓
модель, указанная в поле model

Ключ создаётся в личном кабинете:

https://api.neurozal.ru/panel

Он имеет вид:

sk-nz-...

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

Сам шлюз не выбирает модель вместо пользователя. Выбор выполняется через поле model. Это важный момент: одинаковый код может обращаться к разным моделям, если изменить значение этого поля.

В каталоге есть GPT-5.6, GPT-5.5, GPT-5.4, GPT-4o-mini, GPT-6 Astra, Codex, Claude Opus, Claude Sonnet, Claude Haiku, Gemini Flash, Agnes, Grok, DeepSeek, Kimi, GLM, Qwen и модели генерации изображений.

Важное уточнение: API-ключ не является аккаунтом нейросети

NeuroZal API — это API-ключ для программ, редакторов кода, ботов и автоматизации.

Это не аккаунт ChatGPT или Claude с логином и паролем. Ключ нельзя подключить в мобильном приложении ChatGPT, и он не заменяет подписку Plus.

Модель выбирает пользователь. Один ключ открывает весь каталог моделей, но клиент должен уметь работать с пользовательским base_url либо с одним из поддерживаемых форматов API.

Подключение через OpenAI SDK на Python

Если проект уже использует OpenAI SDK, обычно достаточно заменить адрес и ключ. Остальная структура запроса сохраняется.

from openai import OpenAI

client = OpenAI(
    base_url="https://api.neurozal.ru/v1",
    api_key="sk-nz-..."
)

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {
            "role": "system",
            "content": "Отвечай кратко и по существу."
        },
        {
            "role": "user",
            "content": "Объясни назначение индексов в базе данных."
        }
    ]
)

print(response.choices[0].message.content)

Здесь нужно проверить три строки:

1. base_url указывает на NeuroZal API.
2. api_key содержит ключ из личного кабинета.
3. model содержит имя нужной модели.

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

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

Запрос через curl

Для проверки подключения не обязательно сразу запускать большой проект. Сначала полезно отправить минимальный запрос через curl.

curl https://api.neurozal.ru/v1/chat/completions \
  -H "Authorization: Bearer sk-nz-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {
        "role": "user",
        "content": "Напиши короткое описание очереди задач."
      }
    ]
  }'

Такой тест отделяет проблемы API от проблем конкретного клиента. Если запрос через curl работает, а редактор кода выдаёт ошибку, проверять нужно его настройки: адрес, способ передачи ключа, имя модели и поддерживаемый формат запросов.

Если же минимальный запрос не проходит, стоит сначала сверить ключ и base_url, а затем посмотреть журнал в личном кабинете. Не нужно начинать отладку с расширений редактора, пока базовый запрос не проверен отдельно.

Какие инструменты можно подключить

Названия разделов и полей меняются между версиями программ. Общий принцип остаётся прежним: нужен режим OpenAI-совместимого провайдера, поле адреса API, поле ключа и выбор модели.

Инструмент	Что указать	Где искать настройку
Cursor	base_url, ключ и модель	В настройках моделей и пользовательского провайдера API
Cline	OpenAI-совместимый провайдер, адрес, ключ и модель	В настройках провайдера расширения
Roo Code	OpenAI-совместимый провайдер, адрес, ключ и модель	В разделе выбора и настройки провайдера
Codex CLI	Адрес API, ключ и модель	В конфигурации провайдера средства командной строки
aider	OpenAI-совместимый адрес, ключ и модель	В параметрах запуска или конфигурации модели
Open WebUI	Подключение OpenAI-совместимого API	В разделе подключений и внешних провайдеров
Chatbox	Пользовательский OpenAI-совместимый провайдер	В настройках модели и провайдера
n8n	Адрес, ключ, маршрут и модель	В узле OpenAI-совместимого провайдера либо в узле HTTP-запроса
Свой скрипт	https://api.neurozal.ru/v1, ключ, model	В настройках клиента OpenAI SDK
Бот	Те же параметры, что у собственного скрипта	В серверной конфигурации бота
Claude Code	Базовый адрес Anthropic и ключ	Через ANTHROPIC_BASE_URL и поддерживаемый механизм авторизации

Перед настройкой конкретной программы нужно убедиться, что её версия действительно разрешает менять адрес API. Само наличие поля для ключа OpenAI ещё не гарантирует наличие пользовательского base_url.

Cursor, Cline и Roo Code

Для редакторов и расширений логика подключения одинакова:

• выбрать OpenAI-совместимый режим;
• указать https://api.neurozal.ru/v1;
• добавить ключ sk-nz-...;
• задать модель;
• выполнить короткий тестовый запрос.

Не стоит сразу включать сложную задачу с большим контекстом и изменением нескольких файлов. Сначала лучше проверить простой вопрос. После этого — чтение одного файла, а затем уже переходить к работе с проектом.

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

Codex CLI и aider

Средства командной строки обычно получают параметры из конфигурации или аргументов запуска. Им нужны те же данные: базовый адрес, ключ и имя модели.

Сложность здесь не в самом API, а в том, как конкретная версия программы описывает провайдера. Нельзя без проверки переносить параметры из инструкции для другого выпуска. Сначала следует найти настройку пользовательского OpenAI-совместимого адреса, а затем указать NeuroZal API.

Ключ не следует сохранять в файле, который попадёт в репозиторий. Это особенно важно для общих проектов и открытого исходного кода.

Open WebUI и Chatbox

В программах с графическим интерфейсом нужно искать раздел подключений, моделей или внешних провайдеров. Если поддерживается OpenAI-совместимый API, указываются:

base_url: https://api.neurozal.ru/v1
api_key: sk-nz-...
model: выбранная модель

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

n8n, свои сценарии и боты

В автоматизации можно использовать готовый OpenAI-совместимый узел, если он разрешает заменить базовый адрес. Если такого поля нет, подходит обычный HTTP-запрос к нужному маршруту API.

Для собственного бота шлюз удобен тем, что модель можно выбирать программно. Например, рутинные запросы отправлять лёгкой модели, а более сложные — тяжёлой. Для этого не нужно менять ключ: меняется значение model.

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

Claude Code и Anthropic-совместимый формат

Claude Code требует отдельного внимания. Он работает не только с названием модели Claude, но и с форматом Anthropic.

NeuroZal API поддерживает Anthropic-совместимый маршрут:

/v1/messages

Для Claude Code базовый адрес задаётся через:

export ANTHROPIC_BASE_URL="https://api.neurozal.ru"

В результате запросы должны приходить на:

https://api.neurozal.ru/v1/messages

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

Также нельзя считать, что любой OpenAI-совместимый клиент автоматически работает с Anthropic-форматом. /v1/chat/completions и /v1/messages — разные маршруты с разной структурой запросов. NeuroZal API поддерживает оба варианта, но клиент должен обращаться к подходящему маршруту.

Генерация изображений

Для изображений предусмотрен маршрут:

https://api.neurozal.ru/v1/images/generations

Пример запроса через curl:

curl https://api.neurozal.ru/v1/images/generations \
  -H "Authorization: Bearer sk-nz-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image",
    "prompt": "Минималистичная схема API-шлюза на светлом фоне"
  }'

В каталоге доступны модели генерации изображений gpt-image, DALL-E и Agnes-image. Как и в текстовых запросах, конкретная модель задаётся через поле model.

Текстовый клиент не обязательно поддерживает генерацию изображений, даже если умеет работать с /v1/chat/completions. В таком случае нужно использовать собственный HTTP-запрос, скрипт или программу, которая поддерживает /v1/images/generations.

Что ещё поддерживает шлюз

Помимо OpenAI-совместимых диалоговых запросов и Anthropic-совместимого /v1/messages, доступен маршрут:

/v1/responses

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

Подробности подключения собраны в документации:

https://neurozal.ru/docs

Раздел со статьями:

https://neurozal.ru/articles

Ответы на частые вопросы:

https://neurozal.ru/voprosy

Честные ограничения

Не каждый клиент разрешает менять base_url

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

Нельзя обещать совместимость только потому, что клиент просит ключ OpenAI. Следует проверить наличие поля base_url в конкретной версии.

Часть инструментов требует формат Anthropic

Claude Code и другие клиенты, рассчитанные на Anthropic, могут использовать /v1/messages, а не /v1/chat/completions. Простая замена адреса без учёта формата запроса не всегда сработает.

Если клиент ожидает Anthropic-структуру, нужно использовать Anthropic-совместимый маршрут. Переименование модели не превращает один формат API в другой.

Потоковая выдача и JSON-режим зависят от модели

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

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

Форматы ошибок и лимиты нужно учитывать в коде

При переносе приложения нельзя рассчитывать, что все ошибки будут выглядеть полностью одинаково. Код должен сохранять HTTP-статус и тело ответа, а не сводить любую проблему к сообщению «модель недоступна».

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

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

Расход заметно отличается между моделями

Тяжёлые модели, включая Claude Opus и GPT-5.6, тратят баланс заметно быстрее, чем Gemini Flash и DeepSeek. Это нужно учитывать при подключении автономных редакторов и сценариев, способных выполнять длинные цепочки запросов.

Лёгкие модели — не подмена тяжёлых, а осознанный выбор для рутины: классификации, коротких преобразований, черновиков и простых операций с кодом. Для сложной задачи можно выбрать более тяжёлую модель тем же ключом.

В NeuroZal API используется рублёвый баланс со списанием по факту расхода, без абонентской платы. Токены не сгорают в конце месяца.

Типичные ошибки конфигурации

Лишний /v1. Клиент сам добавляет путь, а пользователь указывает его повторно. В результате получается неверный адрес. Нужно понимать, ожидает поле корневой адрес или полный base_url.

Пропущенный /v1. Обратная ситуация: клиент ждёт полный адрес API, а указан только домен.

Старое значение model. Адрес и ключ заменили, но в коде осталось имя из предыдущей конфигурации.

Не тот формат запроса. Клиент отправляет Anthropic-структуру на /v1/chat/completions либо OpenAI-структуру на /v1/messages.

Ключ вставлен с пробелом. При копировании в начало или конец значения попадает лишний символ.

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

Ожидание одинаковых возможностей от всех моделей. Потоковая выдача, JSON-режим и другие параметры нужно проверять для конкретной модели.

Ключ сохранён в репозитории. Секрет попадает в историю изменений даже после удаления из текущего файла.

Чек-лист подключения из пяти шагов

1. Создать ключ вида sk-nz-... в личном кабинете: https://api.neurozal.ru/panel.
2. Указать OpenAI-совместимый base_url: https://api.neurozal.ru/v1.
3. Выбрать модель и записать её имя в поле model.
4. Проверить минимальный запрос через curl или OpenAI SDK.
5. Подключить рабочий клиент и проверить его формат, потоковую выдачу, JSON-режим и обработку ошибок.

Практический итог

Единый OpenAI-совместимый шлюз убирает необходимость держать отдельный ключ под каждую модель. Cursor, Cline, Roo Code, Codex CLI, aider, Open WebUI, Chatbox, n8n, собственные скрипты и боты можно настраивать через общий принцип: адрес API, ключ и поле model.

Claude Code подключается отдельно через ANTHROPIC_BASE_URL и маршрут /v1/messages. Для изображений используется /v1/images/generations. При этом совместимость всегда нужно проверять по возможностям конкретного клиента: не каждая программа разрешает заменить base_url, а поддержка отдельных режимов зависит от модели.

Для начала достаточно создать ключ в личном кабинете, проверить короткий запрос по документации и только после этого переносить рабочую конфигурацию. Если возникнет проблема, можно написать в поддержку: support@neurozal.ru.

Публичная оферта доступна по адресу https://neurozal.ru/offer, политика конфиденциальности — https://neurozal.ru/privacy.