Руководство по OpenAI API 2026: от первого запроса до продакшна

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

Туториалы 2024 года ссылаются на устаревшие модели и удалённые параметры. Вы ищете «OpenAI streaming example» и находите четыре разные реализации — из которых работают только две.

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

Никаких устаревших параметров. Никаких отговорок в духе «проверьте свежую документацию». Каждый пример протестирован против текущего API.

Ландшафт OpenAI API в 2026 году

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

Chat Completions API (/v1/chat/completions): классика. Stateless, запрос-ответ. Отправляете сообщения — получаете completion. Поддерживает streaming, function calling, JSON mode и structured outputs. Это то, что используют 90% приложений. Если вы не уверены, какой API использовать, используйте этот.

Responses API (/v1/responses): новее, stateful. Поддерживает состояние беседы на стороне сервера, вместо того чтобы вы управляли массивом сообщений. Поддерживает web search, file search и computer use как встроенные инструменты. Лучше подходит для сложных агентных рабочих процессов, где модели нужно оркестрировать несколько инструментов на протяжении нескольких ходов. Компромисс: меньше контроля над историей сообщений, и API всё ещё эволюционирует.

Agents SDK: самое новое дополнение. Фреймворк для создания постоянных AI-агентов со встроенными guardrails, передачей между специализированными агентами и tracing. Более требователен к структуре, чем сырые API — вы меняете гибкость на более быстрое развитие типовых агентных паттернов. Здесь подробно не рассматривается; подробности — в гайде по созданию AI-агентов.

Текущий модельный ряд (июль 2026 года):

Модель	Input $/M	Output $/M	Context	Лучше всего для
GPT-5.5	$5.00	$30.00	1M	Максимальная производительность, сложные рассуждения
GPT-5.4	$2.50	$15.00	1M	Высокая производительность, лучшее соотношение цены и качества
GPT-5.4 Mini	$0.75	$4.50	400K	Повседневные задачи, хороший баланс цены и качества
GPT-5.4 Nano	$0.20	$1.25	128K	Высокообъёмные простые задачи
o4-mini	$1.10	$4.40	200K	Математика, логика, код-загадки (специализация на рассуждениях)

Аутентификация. Задайте свой API-ключ как переменную окружения OPENAI_API_KEY — никогда не хардкодьте его. По управлению ключами в продакшне, ротации, разграничению доступа и архитектуре виртуальных ключей смотрите наш гайд по управлению API-ключами.

Chat Completions API: фундамент

С этого начинается любая интеграция с OpenAI.

Базовый чат-запрос — Python:

from openai import OpenAI

client = OpenAI(
    base_url="https://api.tokspan.com/v1",
    api_key="ts-your-key-here"
)

response = client.chat.completions.create(
    model="gpt-5.5",
    messages=[
        {"role": "system", "content": "You are a software engineer. Answer with code when appropriate."},
        {"role": "user", "content": "Write a Python function to check if a string is a palindrome."}
    ],
    temperature=0.3,       # Low = deterministic, good for code
    max_tokens=500,        # Cap output length
    top_p=0.95             # Nucleus sampling —usually leave at default
)

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

Каждый значимый параметр:

• model — какая модель используется. В продакшне используйте датированные ID (gpt-5.5-2025-06-15), а не алиасы (gpt-5.5). Алиасы молча обновляются до новых снапшотов, которые могут изменить поведение вашего промпта.
• messages — массив объектов сообщений с role («system», «user», «assistant») и content. Системное сообщение задаёт поведение. Сообщение пользователя — это запрос. Сообщения ассистента — предыдущие ответы модели; включайте их для поддержания контекста беседы.
• temperature — от 0 до 2. Используйте 0–0.3 для кода и фактических задач. 0.7–1.0 для чата и творческого письма. 1.0+ для брейншторминга.
• max_tokens — жёсткий лимит длины вывода. Модель останавливается при достижении лимита, даже на середине предложения. Ставьте с запасом (500–4,000) для большинства задач.
• top_p — альтернатива temperature. Обычно оставляйте по умолчанию (1.0) и управляйте случайностью одним temperature.

Правильные системные сообщения. Хорошее системное сообщение конкретно, а не философски. Плохо: «Ты полезный AI-ассистент». Хорошо: «Ты ревьюер Python-кода. Для каждого фрагмента кода определи: (1) потенциальные баги, (2) проблемы производительности, (3) нарушения стиля. Оформи ответ маркированным списком. Каждый пункт — в пределах 30 слов».

Многоходовые беседы. API stateless. Он не помнит ваши предыдущие вызовы.

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

Streaming: ответы в реальном времени

Нестриминговый режим: пользователь ждёт 3–8 секунд, затем видит полный ответ сразу. Стриминговый режим: пользователь видит, как слова появляются в реальном времени, начиная с ~0.4 секунды. Разница в UI — это разница между «ощущается медленно» и «ощущается мгновенно».

Стриминг на Python:

stream = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Explain recursion."}],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

Стриминг на Node.js:

const stream = await client.chat.completions.create({
    model: "gpt-5.5",
    messages: [{ role: "user", content: "Explain recursion." }],
    stream: true
});

for await (const chunk of stream) {
    if (chunk.choices[0]?.delta?.content) {
        process.stdout.write(chunk.choices[0].delta.content);
    }
}

Краевые случаи, которые нужно обработать: Пустые чанки (первые несколько чанков в потоке часто не содержат контента — API ещё обрабатывает). Обрывы соединения (оберните поток в try/except, при сбое на середине повторите с теми же сообщениями). Отслеживание finish_reason (последний чанк содержит finish_reason — проверьте его, чтобы знать, остановилась ли модель естественно или упёрлась в лимит).

Function Calling: дайте LLM инструменты

Модель не выполняет код. Она генерирует JSON, описывающий, какую функцию вызвать и с какими параметрами. Ваш код выполняет функцию.

Вы отправляете результат обратно. Модель использует результат для генерации финального ответа. Это архитектура, стоящая за каждым AI-агентом.

Полный пример погодного агента:

import json

# Step 1: Define the tool
tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Get current weather for a city. Returns temperature in Celsius and conditions.",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "City name, e.g. 'Tokyo'"}
            },
            "required": ["city"]
        }
    }
}]

# Step 2: User asks a question that needs the tool
response = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "What's the weather in Tokyo?"}],
    tools=tools,
    tool_choice="auto"  # Model decides whether to use a tool
)

# Step 3: Check if model wants to call a tool
msg = response.choices[0].message
if msg.tool_calls:
    tool_call = msg.tool_calls[0]
    args = json.loads(tool_call.function.arguments)

    # Step 4: Execute the function (in reality, call a weather API)
    weather_result = get_actual_weather(args["city"])

    # Step 5: Send the result back
    messages = [
        {"role": "user", "content": "What's the weather in Tokyo?"},
        msg,  # The assistant's tool_call message
        {"role": "tool", "tool_call_id": tool_call.id, "content": str(weather_result)}
    ]

    final_response = client.chat.completions.create(
        model="gpt-5.5",
        messages=messages
    )
    print(final_response.choices[0].message.content)

Параллельный function calling. Определите несколько инструментов. Модель может запросить сразу несколько, если они независимы — «получи погоду в Токио И Осаке». Ваш код должен обрабатывать несколько tool_calls в ответе, выполнять их параллельно (asyncio.gather) и отправлять все результаты вместе.

Лучшие практики function calling. Описания инструментов — это промпты; пишите их чётко и включайте примеры того, когда использовать каждый инструмент. Ограничивайте параметры строго — используйте enums вместо строк произвольного текста. Гайд OpenAI по function calling детально покрывает краевые случаи вроде стриминговых tool calls и параллельного выполнения.

Делайте инструменты идемпотентными. Когда выполнение инструмента падает, отправьте сообщение об ошибке обратно модели — она часто может восстановиться, попробовав другие параметры.

Сравнение function calling по провайдерам OpenAI, Anthropic, Google и DeepSeek — включая то, какие функции переживают перевод в OpenAI-совместимый формат — полностью разобрано в сравнении tool calling.

Structured Outputs: гарантированный JSON

JSON mode (response_format={"type": "json_object"}) намекает, что вам нужен JSON. Модель обычно соглашается. Structured Outputs (response_format={"type": "json_schema", ...}) гарантирует это — выборка токенов модели ограничивается так, чтобы она производила только валидный JSON, соответствующий вашей схеме.

Когда что использовать. JSON mode: быстрый прототипинг, внутренние инструменты, случаи, где вы можете пережить редкий невалидный JSON. Structured Outputs: продакшн-API, пользовательские функции, любой случай, где невалидный JSON вызывает каскадный сбой. Документация OpenAI по Structured Outputs покрывает полный синтаксис определения схемы и поддерживаемые модели.

Определение схемы — пример парсера резюме:

response = client.chat.completions.create(
    model="gpt-5.4",  # Structured Outputs supported on GPT-5.4+
    messages=[{"role": "user", "content": f"Extract information from this resume:\n\n{resume_text}"}],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "resume_extraction",
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "skills": {"type": "array", "items": {"type": "string"}},
                    "years_experience": {"type": "integer"},
                    "current_role": {"type": "string"}
                },
                "required": ["name", "skills", "years_experience"]
            }
        }
    }
)

resume_data = json.loads(response.choices[0].message.content)
# Guaranteed to match your schema. No try/except json.loads needed.

Чек-лист продакшн-развёртывания

Управление окружением. API-ключи — в хранилище секретов (AWS Secrets Manager, HashiCorp Vault, Doppler), а не в файлах .env. Ротируйте ключи каждые 90 дней. Используйте отдельные ключи для разработки, стейджинга и продакшна с разными бюджетными лимитами и allowlist’ами моделей.

Обработка ошибок для продакшна. Оберните каждый вызов API в retry с экспоненциальным backoff и джиттером. Используйте circuit breaker для провайдеров, которые стабильно падают, — прекращайте маршрутизацию к ним на 30 секунд, проверяйте, возобновляйте, если всё здорово. Никогда не возвращайте пользователям сырые ошибки API — мапьте их на понятные сообщения и логируйте детали внутренне.

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

Неожиданный счёт на $500 появляется, когда за расходами никто не следил. Ежедневные сводки расходов просматриваются за 10 секунд.

Управление лимитами запросов. Знайте лимиты RPM и TPM своего тарифа. Читайте заголовки x-ratelimit-remaining-* в каждом ответе. Снижайте темп при 30% остатка. Останавливайтесь на 10%.

Полную архитектуру управления лимитами — от реактивного backoff до прогнозного троттлинга — смотрите в нашем гайде по обработке лимитов в продакшне.

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

Компромисс — сниженный контроль над путём запроса. Для большинства команд сэкономленное время перевешивает переданный контроль.

FAQ

В чём разница между GPT-5.5 и o4-mini?

GPT-5.5 — универсальная модель для чата, кодинга, анализа и генерации. o4-mini — модель, специализированная на рассуждениях: она дольше думает перед ответом, поэтому сильнее в математике, логических задачах и формальных рассуждениях, но медленнее и дороже за токен.

Используйте GPT-5.5 для повседневных задач. Используйте o4-mini для задач, где обычно потянулись бы за калькулятором или формальным доказательством.

Нужно ли мне использовать Responses API вместо Chat Completions?

Пока нет. Chat Completions стабилен, широко поддерживается и покрывает 90% сценариев. Responses API добавляет управление состоянием и встроенные инструменты (web search, file search), но он новее и эволюционирует.

Начните с Chat Completions. Мигрируйте на Responses API, когда понадобятся его специфические функции.

Как сократить расходы на OpenAI API?

Используйте GPT-5.4 Mini ($0.75/$4.50) вместо GPT-5.5 ($5/$30) для простых задач. Включите prompt caching — скидка 50% на кэшированный ввод. Используйте batch API для несрочной работы — скидка 50% при обороте за 24 часа.

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

Можно ли использовать OpenAI SDK с не-OpenAI моделями?

Да. Большинство провайдеров предлагают OpenAI-совместимые endpoints.

Измените base_url и api_key. Ваш код остаётся прежним. Это главное преимущество OpenAI-совместимого стандарта — вы не привязаны к одному провайдеру.

Что будет, когда OpenAI объявит устаревшей используемую мной модель?

OpenAI обычно предупреждает за 1–3 месяца. Фиксируйтесь на датированных ID моделей (gpt-5.5-2025-06-15), а не на алиасах (gpt-5.5), чтобы контролировать момент миграции.

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

OpenAI API — отраслевой стандарт не просто так: зрелые SDK, исчерпывающая документация и экосистема, которая поддерживает его первой. Но 2026-й — первый год, когда этот стандарт даёт трещину: нативный протокол Anthropic, автоматический function calling от Google и ценовое давление DeepSeek — всё это тянет разработчиков к функциям, которые не переживают перевод через /v1/chat/completions. Вопрос, за которым стоит следить: станет ли Agents SDK от OpenAI следующим отраслевым стандартом, который вновь объединит экосистему, или ускорит фрагментацию, введя возможности, доступные только на собственной инфраструктуре OpenAI?

Начать кодить — освойте API OpenAI по-своему. Затем добавьте Claude, Gemini и DeepSeek через тот же SDK, когда будете готовы, — потому что единственная безопасная ставка в 2026 году — это код, который работает у любого провайдера.