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

openaiapillmинтеграцияsdkitпрактика

Что такое 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) — для сложных, локальная — для чувствительных данных. Подробнее о выборе — в гайде по выбору модели.

Быстрый старт

  1. Получите ключ: регистрация по email, пополнение в USDT от $10 — johellm.com.
  2. export OPENAI_BASE_URL=https://api-vpn.johellm.com/v1
  3. export OPENAI_API_KEY=sk-ваш-ключ
  4. Запустите ваш существующий код — он уже совместим.

Один ключ открывает 16 моделей: GPT, Claude, DeepSeek, Qwen, GLM, Kimi, MiniMax и бесплатную north-mini-code для проверки интеграции.