OpenAI Responses API: первый запрос и настройка

Если нужно отправить модели текст и получить текстовый ответ, Responses API сводит задачу к короткой цепочке: SDK берёт ключ из окружения, responses.create отправляет модель и входные данные, а output_text отдаёт собранный текст ответа. Позже к этому же интерфейсу можно добавить инструменты, файлы, потоковую выдачу и состояние диалога. Но первый вызов лучше оставить маленьким: так сразу видно, где заканчивается настройка клиента и начинается логика приложения.

Что нужно подготовить

Создайте API-ключ в проекте OpenAI и передайте его процессу через переменную OPENAI_API_KEY. Не вставляйте секрет прямо в исходник и не коммитьте файл .env в репозиторий. Официальные SDK читают ключ из окружения автоматически — это показано в Developer quickstart.

В macOS или Linux переменная задаётся так:

export OPENAI_API_KEY="your_api_key_here"

В PowerShell:

setx OPENAI_API_KEY "your_api_key_here"

После setx откройте новый терминал: уже запущенный процесс не увидит изменённое окружение. Для одноразового запуска в текущем окне PowerShell можно использовать $env:OPENAI_API_KEY = "your_api_key_here", но такой способ не должен попадать в историю CI или общий скрипт.

Установите официальное SDK для выбранного языка:

python -m pip install openai

npm install openai

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

После первого рабочего примера может понадобиться не вызов модели, а доступ к зарубежному пользовательскому сервису. Для общего знакомства с вариантами оформления через посредника есть каталог услуг Amber Market. Это не пополнение баланса OpenAI API: отдельного предложения для такой операции в публичном каталоге нет. Перед оформлением проверьте актуальные условия, подтвердите email кодом, сверьте сумму и доступный способ оплаты; магазин указывает оплату через СБП и выдаёт дальнейшую инструкцию по выбранному предложению.

Первый текстовый запрос из Python

Минимальный вызов выглядит так:

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="your-available-model",
    input="Объясни в одном предложении, что делает Responses API.",
)

print(response.output_text)

OpenAI() здесь не получает ключ аргументом: SDK находит OPENAI_API_KEY в окружении. В responses.create нужно указать model и input. Для короткого запроса строка подходит лучше всего; когда появятся роли, изображения или файлы, input можно представить более структурированными элементами.

Проверять нужно не только наличие объекта response, но и полезный результат:

if not response.output_text.strip():
    raise RuntimeError(f"Ответ без текста: {response.id}")

print(f"response_id={response.id}")
print(response.output_text)

В простом текстовом сценарии output_text — удобное свойство официального SDK, которое собирает текстовые части ответа. Не привязывайтесь к предположению, что текст всегда лежит в output[0].content[0].text: в массиве output могут находиться вызовы инструментов и другие элементы. Именно это различие начинает иметь значение, когда к запросу добавляется не только генерация текста. Подробнее структура разобрана в руководстве Text generation.

Для устойчивых правил ответа используйте instructions, а пользовательский вопрос оставляйте в input:

response = client.responses.create(
    model="your-available-model",
    instructions="Отвечай кратко, на русском языке, без Markdown.",
    input="Что такое идемпотентность?",
)

print(response.output_text)

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

Тот же запрос из JavaScript

Для Node.js с официальным пакетом код будет таким:

import OpenAI from "openai";

const client = new OpenAI();

const response = await client.responses.create({
  model: "your-available-model",
  input: "Объясни в одном предложении, что делает Responses API.",
});

if (!response.output_text?.trim()) {
  throw new Error(`Ответ без текста: ${response.id}`);
}

console.log(`response_id=${response.id}`);
console.log(response.output_text);

Запустите файл в режиме, поддерживающем ESM и await на верхнем уровне, либо поместите вызов в async-функцию. Если проект использует CommonJS, настройте формат модулей под его текущую конфигурацию; сам вызов API от этого не меняется.

Инструкции передаются тем же объектом:

const response = await client.responses.create({
  model: "your-available-model",
  instructions: "Отвечай кратко, на русском языке, без Markdown.",
  input: "Что такое идемпотентность?",
});

console.log(response.output_text);

Минимальная проверка здесь полезнее вывода всего объекта в лог. Идентификатор response.id поможет найти конкретную попытку в диагностике, а пустой output_text остановит обработку до того, как пустая строка попадёт пользователю или в базу данных.

Что меняется при переходе с Chat Completions

Миграция начинается не с механической замены имени метода. В Chat Completions вы привыкли передавать messages; в Responses API вход описывается через input, причём он может быть простой строкой или массивом элементов. Ответ тоже имеет другую форму: вместо чтения только привычного choices[0].message.content используйте output_text для обычного текстового результата и учитывайте, что output может содержать не только сообщение.

Переезд удобно делать по одному вызову:

1. Зафиксируйте исходный пользовательский запрос и ожидаемое свойство результата — например, непустой текст и допустимый формат.
2. Сопоставьте messages с input, а системные или разработческие указания вынесите в instructions, если это соответствует вашей логике.
3. Замените чтение ответа на response.output_text и добавьте проверку пустого результата.
4. Проверьте обработку ошибок, логирование response.id, таймауты и повторные попытки. Повторить HTTP-запрос легко; сложнее понять, успела ли первая попытка породить побочный эффект.
5. Только после этого подключайте инструменты и дополнительные элементы output.

Сверяйте отдельные параметры с руководством по миграции на Responses API. Не все настройки Chat Completions переносятся один к одному, а поддержка конкретной модели и её лимиты зависят от текущего проекта.

Границы, о которых лучше помнить сразу

Responses API — интерфейс вызова модели, а не пользовательская подписка ChatGPT и не инструкция по пополнению баланса. Секретный ключ хранится на стороне вашего приложения; в браузерный клиент его не отправляют. Для клиентского приложения обычно нужен собственный серверный endpoint, который принимает безопасно ограниченный запрос и вызывает OpenAI SDK.

Кроме того, проверьте настройки хранения и обработки данных для конкретного проекта. Политика Responses API зависит от параметров запроса и настроек организации; для чувствительных данных сверяйтесь с актуальным разделом Data controls, а не делайте вывод только по одному примеру кода.

Первый успешный тест можно считать завершённым, если SDK прочитал ключ из окружения, запрос вернул объект ответа, output_text непустой, а выбранная модель действительно доступна проекту. Всё остальное — инструменты, потоковая выдача, состояние диалога и специализированные форматы — лучше добавлять следующим небольшим изменением, сохраняя этот рабочий базовый вызов.