Подключение OpenAI API: аккаунт, ключ, Base URL и первый запрос (2026)

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

Ниже — порядок реальных действий: аккаунт и проект, создание ключа, пополнение, установка SDK, первый вызов Responses API, просмотр расхода, разбор ошибок 401 и 429 и, наконец, переход на OpenAI-совместимый шлюз через Base URL. Примеры в основном построены на Responses API; для старых инструментов, которые поддерживают только Chat Completions, интерфейс заменяется по той же логике.

Примечание: OpenAI, ChatGPT и GPT — товарные знаки OpenAI. Примеры описывают публичное поведение интерфейсов по состоянию на октябрь 2026 года; названия моделей, лимиты и цены уточняйте на странице тарифов и в официальной документации.

1. Аккаунт, организация и проект: в чём разница

Платформа OpenAI устроена как минимум на трёх уровнях, и их смешение — самая частая причина ошибок:

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

Типичное заблуждение — считать подписку ChatGPT балансом API. Это разные вещи: подписка даёт доступ к чат-продукту, а API оплачивается отдельно по фактическим вызовам. Перед подключением команды стоит договориться, кто отвечает за аккаунт, кто за оплату и у кого права администратора, иначе при смене сотрудников будет непонятно, кому принадлежит ключ.

2. Порядок создания API-ключа

Выполняйте шаги по порядку, не пропуская:

Войдите в консоль API под администратором и убедитесь, что выбрана нужная организация.
Создайте или выберите проект внутри организации и разделите среды «разработка / тест / производство».
Перейдите на страницу API Keys проекта и создайте новый ключ.
Дайте ключу понятное имя, например «production-чат-бот».
Сразу скопируйте полный ключ и сохраните его в менеджере паролей или в хранилище секретов платформы.
При необходимости задайте права проекта, бюджет или лимит и сохраните изменения.

Полный ключ обычно показывается только при создании. То, что на странице остались лишь первые и последние символы, — нормально; рассчитывать на повторное копирование не стоит. Если ключ потерян, создайте новый и отключите старый, а не пытайтесь его восстановить.

3. Пополнение, биллинг и лимиты

Предоплата или постоплата зависит от типа аккаунта и региона; ориентируйтесь на то, что показывает консоль. Перед подключением проверьте три вещи:

Поддерживает ли система оплаты вашу карту или канал.
Каков биллинговый период и как получить счёт.
Можно ли настроить для проекта напоминания о бюджете и жёсткий лимит.

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

4. Установка SDK и первый запрос curl

Сначала установите официальный Python SDK:

python3 -m pip install --upgrade openai
export OPENAI_API_KEY="sk-ваш-ключ"
export OPENAI_BASE_URL="https://api.openai.com/v1"
export OPENAI_MODEL="имя модели из прайс-листа или официальной документации"

Вызовите Responses API через curl и убедитесь, что адрес, ключ и сеть работают:

curl -sS "$OPENAI_BASE_URL/responses" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$OPENAI_MODEL"'",
    "input": "Объясни одной фразой, что такое API-шлюз."
  }'

Не пишите имя модели по памяти: скопируйте актуальное название со страницы тарифов или из официальной документации и сохраните в переменную OPENAI_MODEL. Если возвращается 200 и в теле ответа есть вывод, цепочка работает. При 401 сначала проверяйте ключ, при 404 — Base URL и имя модели.

5. Первый вызов на Python

Ниже — минимальный запрос к Responses API с выводом текстового результата:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["OPENAI_API_KEY"],
    base_url=os.environ.get("OPENAI_BASE_URL", "https://api.openai.com/v1"),
)

resp = client.responses.create(
    model=os.environ["OPENAI_MODEL"],
    input="В трёх предложениях опиши границы своих возможностей.",
)

print(resp.output_text)

Если ваш фреймворк поддерживает только Chat Completions, замените вызов на client.chat.completions.create(...), а сообщения передайте в messages. Пути запросов у двух интерфейсов различаются; при смешивании чаще всего возникает 404.

6. Как читать расход и счёт

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

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

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

7. Как разбирать ошибки 401 и 429

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

У 429 две причины: ограничение скорости и недостаток баланса. Смотрите код ошибки и заголовки ответа, не снижайте скорость автоматически. insufficient_quota обычно указывает на баланс или лимит — нужно пополнить счёт или изменить лимит проекта; экспоненциальная пауза подходит только для ошибок скорости. Повтор запроса имеет смысл только для 429, 5xx и сетевых ошибок; для 400, 401, 403 и 404 повтор лишь расходует средства. Более подробный порядок диагностики описан в руководстве по ошибкам OpenAI API; актуальные модели и условия — на странице тарифов.

8. Прямое подключение или совместимый шлюз

Критерий	Прямое подключение	OpenAI-совместимый шлюз
Адрес	`https://api.openai.com/v1`	Base URL шлюза, обычно также заканчивается на `/v1`
Аккаунт и оплата	Аккаунт OpenAI, доступные официальные способы оплаты	Аккаунт на сайте шлюза, пополнение в юанях и счёт
Сеть	Зависит от локальной сети и трансграничного канала	Обычно есть точка доступа, доступная из Китая
Набор моделей	Только модели OpenAI	Может предоставлять модели нескольких поставщиков; смотрите страницу тарифов
Биллинг	Официальный счёт	Внутренний баланс и история расхода
Сбои	Обращение в поддержку OpenAI	Шлюз разбирается с вышестоящим провайдером, пользователь сохраняет request ID
Когда подходит	Только OpenAI и уже есть удобный платёжный путь	Команды в Китае, несколько моделей, единый счёт

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

9. Переход на совместимый шлюз: меняем только Base URL

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

Зарегистрируйтесь в шлюзе и создайте ключ на странице регистрации.
Замените OPENAI_BASE_URL на адрес шлюза, сохранив /v1.
Замените ключ на ключ шлюза и не смешивайте два набора ключей.
Скопируйте имя модели со страницы тарифов шлюза, не полагайтесь на официальные названия.
Сначала вызовите /v1/models и минимальный запрос, затем переводите производственный трафик.
Оставьте официальный или резервный маршрут как план отката.

«Совместимость с OpenAI» означает совместимость форматов запроса и ответа, но не полное совпадение всех расширенных возможностей. Поддержку файлов, пакетной обработки и вызова инструментов нужно проверять по документации шлюза по пунктам, а не считать, что всё доступно по умолчанию. Подробнее о границах совместимости — в отдельном описании OpenAI-совместимого API; актуальный перечень возможностей — на странице тарифов.

10. Безопасность ключей и чек-лист перед запуском

Утечка ключа приводит к прямым расходам. Минимальные требования:

храните ключ только в серверных переменных окружения или сервисе управления секретами, не в клиентском коде и не в Git;
разделяйте ключи по средам, тест и производство не должны использовать один ключ;
указывайте для каждого ключа ответственного и назначение, своевременно отключайте его при увольнении или смене проекта;
не печатайте полный ключ в логах, оставляйте только последние четыре символа;
регулярно меняйте ключи и немедленно отзывайте их при подозрительных вызовах.

Перед запуском проверьте по пунктам:

[ ] принадлежность аккаунта, организации и проекта понятна;
[ ] способ оплаты работает, напоминания о бюджете настроены;
[ ] ключ хранится в переменных окружения или хранилище секретов;
[ ] в Base URL только один /v1;
[ ] минимальный запрос возвращает 200 и корректный ответ;
[ ] настроены пауза при 429 и повтор при 5xx;
[ ] в логах расхода есть request ID, модель и время выполнения;
[ ] резервный маршрут и процедура отключения ключа проверены.

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

API-ключ и подписка ChatGPT — это одно и то же?

Нет. Подписка и API оплачиваются отдельно, а API-ключ создаётся и управляется только на платформе API. При возмещении расходов команде нужно разделять эти две статьи.

Почему после создания не видно полного ключа?

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

Куда указывать Base URL?

До домена включительно плюс /v1, без /chat/completions и /responses. Путь добавляет SDK или сам запрос; лишний сегмент приводит к 404.

Можно ли использовать один ключ для нескольких проектов?

Технически можно, но с точки зрения управления это не рекомендуется. Разделение ключей по проектам или средам позволяет контролировать права, отслеживать расход и ограничивать последствия утечки.

Обязательно ли командам в Китае использовать шлюз?

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

Что дальше

Сначала добейтесь успешного минимального запроса, затем подключайте бизнес-логику. Если нужны пополнение в юанях и единая точка доступа к нескольким моделям, начните с регистрации в ZSQH AI Gateway; модели и цены — на странице тарифов.