OpenAI SDK: что это и почему с ним работают не только модели GPT

OpenAI SDK — это официальная библиотека, которая упрощает обращение к API OpenAI из кода. Вместо ручной сборки HTTP-запросов вы вызываете функции, а библиотека формирует запрос, подставляет ключ, разбирает ответ и повторяет запрос при временных сбоях. Ниже разберём, что такое OpenAI SDK, на каких языках он есть и почему через него можно работать не только с GPT, но и с Claude, Gemini и DeepSeek, изменив один параметр.

Сведения о библиотеках основаны на их официальных README на GitHub (openai-python и openai-node) и руководствах OpenAI на момент проверки: требования к версиям языков там меняются, сверяйте их при установке.

Что делает SDK

Под капотом любой запрос к API — это HTTP: адрес, заголовок авторизации и тело JSON. SDK берёт на себя рутину:

• подставляет заголовок Authorization: Bearer ...;
• собирает путь, например /chat/completions, из базового адреса;
• превращает JSON-ответ в объекты с подсказками типов;
• разбирает потоковые ответы (SSE);
• повторяет запросы при временных ошибках и выбрасывает типизированные исключения.

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

На каких языках он есть

У OpenAI есть официальные библиотеки для Python (по README, нужен Python 3.10 или новее), TypeScript и JavaScript (Node.js 22 и 24 LTS, минимальная — 22; также заявлены Deno и Bun), а в руководствах OpenAI приведены примеры для Go, Java, C# и Ruby. Установка в Python и Node.js:

pip install openai
npm install openai

Для языков без официальной библиотеки достаточно обычного HTTP-клиента: формат запроса одинаков, нужно лишь собрать JSON и передать заголовок авторизации.

Как с ним работают не только GPT-модели

Клиент принимает необязательный параметр base_url (в Node.js — baseURL). Если его не задать, запросы идут на адрес OpenAI. Если задать адрес шлюза, они идут туда. Формат запроса остаётся тем же, меняется только модель и ключ.

from openai import OpenAI

client = OpenAI(
    base_url="https://api.zukko.pro/v1",
    api_key="fetch_ваш_ключ",
)

for model in ["claude-sonnet-5-5", "gpt-6.1-sol", "deepseek-v4.1-flash"]:
    r = client.chat.completions.create(
        model=model,
        messages=[{"role": "user", "content": "Объясни, что такое токен, одним предложением"}],
        max_tokens=200,
    )
    print(model, "->", r.choices[0].message.content, "| токенов:", r.usage.total_tokens)

Тот же код на Node.js:

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.zukko.pro/v1",
  apiKey: process.env.ZUKKO_API_KEY,
});

const r = await client.chat.completions.create({
  model: "claude-sonnet-5-5",
  messages: [{ role: "user", content: "Привет" }],
});
console.log(r.choices[0].message.content);

Можно обойтись и без правок кода: библиотеки читают переменные окружения OPENAI_BASE_URL и OPENAI_API_KEY. Тогда OpenAI() без аргументов уже смотрит на шлюз.

export OPENAI_BASE_URL="https://api.zukko.pro/v1"
export OPENAI_API_KEY="fetch_ваш_ключ"

Адрес для OpenAI-формата всегда заканчивается на /v1, это одно из самых частых мест ошибок; разбор есть в статье base URL с /v1 или без↗. Подробнее про сам стандарт — в статье OpenAI compatible API↗.

Где у этого подхода границы

Совместимость касается формы запросов, но не всего, что умеет платформа OpenAI. Что нужно проверить заранее:

• Какие эндпоинты есть у шлюза. У Zukko это POST /v1/chat/completions, POST /v1/responses и GET /v1/models. Методы SDK для файлов, пакетной обработки или эмбеддингов будут обращаться к адресам, которых в документации шлюза нет.
• Какие параметры принимает конкретная модель. Форма одинакова, но поддержка отдельных параметров (например, temperature или вызова инструментов) зависит от модели: если запрос отклонён, проверьте текст ошибки и уберите лишний параметр.
• Кэш для Claude. В OpenAI-формате шлюз для Claude не видит, сколько входа пришло из кэша, и весь вход идёт по цене входа. Скидку за кэш даёт Anthropic-формат (/v1/messages), а для него используется официальный Anthropic SDK с адресом https://api.zukko.pro без /v1. У GPT-моделей кэш виден в обоих форматах. Подробнее в документации по лимитам и кэшу↗.
• Потоковые ответы. Последний фрагмент потока содержит usage и пустой массив choices, поэтому перед chunk.choices[0] проверяйте if chunk.choices:.

Обработка ошибок

SDK превращает HTTP-ошибки в исключения. В Python основные классы лежат в пространстве имён openai:

import openai

try:
    r = client.chat.completions.create(
        model="gpt-6.1-sol",
        messages=[{"role": "user", "content": "Привет"}],
    )
except openai.AuthenticationError:
    print("401: проверьте ключ")
except openai.RateLimitError:
    print("429: лимит ключа или ограничение провайдера, повторите позже")
except openai.APIStatusError as e:
    print("Ошибка API:", e.status_code)
except openai.APIConnectionError:
    print("Нет соединения с сервером")

Коды шлюза: 401 неверный ключ, 402 не хватает баланса, 403 model_not_allowed_for_key, 404 model_not_found, 413 слишком большой запрос, 429 лимит ключа или ограничение провайдера, 503 провайдер недоступен или модель выключена. Код 402 попадёт в общий APIStatusError с полем status_code. У библиотеки есть и собственные автоматические повторы (параметр max_retries): подберите их число под вашу задачу.

Сколько стоит вызов

Возьмём запрос на 1000 токенов входа и 500 токенов выхода. Формула: вход × цена входа + выход × цена выхода, цены на 18 октября 2026.

Какая из моделей подходит вашей задаче, решают проверка и ваши данные, а не цена. Актуальный список и цены: GET https://api.zukko.pro/v1/models или страница «Модели» в кабинете.

Более полные примеры на Python собраны в документации по Python↗.

Частые вопросы

OpenAI SDK работает только с OpenAI?

Нет. Это клиент OpenAI-совместимого протокола. Если сервер поддерживает тот же формат запросов, библиотеку можно направить на него через base_url.

Нужно ли платить за сам SDK?

Нет, библиотека бесплатна и открыта. Платить нужно за токены у того, чей API вы вызываете.

Что выбрать для Claude: OpenAI SDK или Anthropic SDK?

Если нужна скидка за кэш, используйте Anthropic SDK и Anthropic-формат. Если важнее единый код для всех моделей, подойдёт OpenAI SDK, но для Claude весь вход пойдёт по цене входа.

Как проверить, что подключение работает?

Вызовите client.models.list() или GET /v1/models, затем отправьте короткий запрос. Ключ создаётся в кабинете↗, доступ из России идёт через шлюз, оплата СБП, картой MasterCard или криптой.