OpenAI-совместимый API: что это, зачем нужен и как подключить любой инструмент
Что такое OpenAI-совместимый API
Формат Chat Completions от OpenAI (POST /v1/chat/completions) стал де-факто стандартом индустрии: его поддерживают провайдеры (Anthropic через шлюзы, DeepSeek, Mistral, Together, OpenRouter), локальные серверы (vLLM, llama.cpp, Ollama, LM Studio) и почти все инструменты разработчика (Cline, Continue, LangChain, LlamaIndex).
«OpenAI-совместимый» означает: сервер принимает те же пути, заголовки и JSON, что и настоящий OpenAI API. Следствие — любой код, написанный под OpenAI, работает с таким сервером после замены двух строк: base_url и api_key.
from openai import OpenAI
client = OpenAI(
base_url="https://api-vpn.johellm.com/v1", # ← была api.openai.com/v1
api_key="sk-ваш-ключ", # ← ключ нового провайдера
)
Всё остальное — модели сообщений, стриминг, function calling, структурированный вывод — остаётся как было.
Анатомия запроса
curl https://api-vpn.johellm.com/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-ваш-ключ" \
-d '{
"model": "deepseek-v4.1-flash",
"messages": [
{"role": "system", "content": "Ты помощник, отвечай кратко."},
{"role": "user", "content": "Что такое эмбеддинг?"}
],
"temperature": 0.7,
"stream": false
}'
Ключевые поля:
| Поле | Что делает |
|---|---|
model |
id модели у конкретного провайдера — единственное, что меняется между провайдерами |
messages |
история диалога: system, user, assistant, tool |
stream |
true — ответ приходит чанками Server-Sent Events |
tools |
описания функций для function calling |
response_format |
{"type": "json_object"} или JSON Schema для структурированного вывода |
Ответ тоже стандартизирован: choices[0].message.content, счётчики usage.prompt_tokens / usage.completion_tokens — по ним считается стоимость.
Какие эндпоинты обычно поддерживаются
/v1/chat/completions— основной, есть везде/v1/models— список доступных моделей/v1/embeddings— векторы для RAG (зависит от провайдера)/v1/completions— легаси-формат без чата, почти не используется
Проверить совместимость сервера за 5 секунд:
curl https://api-vpn.johellm.com/v1/models \
-H "Authorization: Bearer sk-ваш-ключ"
Если в ответе JSON со списком data[].id — сервер говорит на языке OpenAI.
Подключение популярных инструментов
Python (официальный SDK)
client = OpenAI(base_url="https://api-vpn.johellm.com/v1", api_key=key)
Node.js
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api-vpn.johellm.com/v1",
apiKey: process.env.JOHE_API_KEY,
});
LangChain
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(
base_url="https://api-vpn.johellm.com/v1",
api_key=key,
model="qwen/qwen4-max",
)
Cline / Continue / прочие IDE-агенты
В настройках провайдера выбираете «OpenAI Compatible», вставляете base URL и ключ. Подробный разбор — в статье Claude Code, Cline и Continue через российский API.
Переменные окружения
Многие CLI-инструменты уважают стандартные переменные:
export OPENAI_BASE_URL="https://api-vpn.johellm.com/v1"
export OPENAI_API_KEY="sk-ваш-ключ"
Подводные камни
1. Разные id моделей. gpt-4o у OpenAI, openai/gpt-4o у OpenRouter, свой id у каждого шлюза. Всегда сверяйтесь с /v1/models конкретного провайдера.
2. Не все параметры проходят насквозь. Экзотика вроде logit_bias или seed может игнорироваться шлюзом или нижележащей моделью. Базовый набор (temperature, max_tokens, stream, tools) работает везде.
3. Лимиты токенов отличаются. max_tokens выше лимита модели вернёт 400. Контекстные окна у моделей разные — от 128K до 1M.
4. Стриминг через прокси. Если между вами и API стоит корпоративный прокси или CDN с буферизацией, SSE-чанки могут «слипаться». Проверяйте stream: true отдельно.
5. Счёт токенов ≠ счёт символов. Для русского текста токенов обычно в 2–3 раза больше, чем слов. Считайте стоимость по usage из ответа, а не по длине строк.
Зачем это всё: свобода миграции
Главная ценность совместимого API — отсутствие вендор-лока. Код, написанный один раз, работает с:
- облачными провайдерами (OpenAI, DeepSeek, шлюзы к Claude);
- локальным сервером vLLM или Ollama на своём железе;
- любым будущим провайдером, который появится завтра.
Переключение — одна переменная окружения. Это позволяет строить пайплайн так: дёшевая модель (DeepSeek, GLM-flash) для массовых задач, дорогая (Claude, GPT) — для сложных, локальная — для чувствительных данных. Подробнее о выборе — в гайде по выбору модели.
Быстрый старт
- Получите ключ: регистрация по email, пополнение в USDT от $10 — johellm.com.
export OPENAI_BASE_URL=https://api-vpn.johellm.com/v1export OPENAI_API_KEY=sk-ваш-ключ- Запустите ваш существующий код — он уже совместим.
Один ключ открывает 16 моделей: GPT, Claude, DeepSeek, Qwen, GLM, Kimi, MiniMax и бесплатную north-mini-code для проверки интеграции.