OpenAI Responses API — что это и как использовать

Responses API — это новый унифицированный интерфейс OpenAI для работы с моделями, который объединяет возможности Chat Completions и Assistants API в одном эндпоинте. Вместо массива messages он принимает упрощённый параметр input и из коробки поддерживает вызов инструментов, веб-поиск и режим рассуждений (reasoning).

В этом гайде разберём, что такое Responses API, чем он отличается от Chat Completions, и покажем рабочие примеры — в том числе как пользоваться им из России через AITUNNEL без VPN и с оплатой в рублях.

Что такое Responses API

Responses API — это «следующее поколение» API OpenAI. Его ключевые идеи:

• Единый эндпоинт /v1/responses для текста, инструментов, веб-поиска и reasoning.
• Упрощённый ввод: можно передать обычную строку в input вместо массива сообщений.
• Встроенные инструменты: веб-поиск и вызов функций подключаются параметрами запроса.
• Совместимость: задуман как drop-in замена и работает с официальным OpenAI SDK.

AITUNNEL предоставляет полностью OpenAI-совместимый Responses API. Базовый URL:

https://api.aitunnel.ru/v1/responses

Responses API vs Chat Completions: в чём разница

Если у вас уже есть код на Chat Completions — он продолжит работать. Responses API стоит выбирать, когда нужен простой интерфейс с встроенным веб-поиском и инструментами.

Быстрый старт (Python, OpenAI SDK)

Достаточно поменять base_url на адрес AITUNNEL и подставить ваш ключ:

from openai import OpenAI

client = OpenAI(
    api_key="sk-aitunnel-xxx",
    base_url="https://api.aitunnel.ru/v1/"
)

response = client.responses.create(
    model="gpt-5.2",
    input="Объясни квантовую запутанность простыми словами"
)

print(response.output_text)

Быстрый старт (JavaScript / TypeScript)

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-aitunnel-xxx',
  baseURL: 'https://api.aitunnel.ru/v1/'
});

const response = await client.responses.create({
  model: 'gpt-5.2',
  input: 'Напиши слоган для кофейни в стиле минимализма'
});

console.log(response.output_text);

Запрос напрямую (cURL / HTTP)

Responses API можно вызывать и без SDK — обычным POST-запросом:

curl -X POST https://api.aitunnel.ru/v1/responses \
  -H "Authorization: Bearer sk-aitunnel-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.2",
    "input": "В чём смысл жизни?",
    "max_output_tokens": 9000
  }'

Системные инструкции

Поведение модели задаётся параметром instructions (аналог system-промпта):

response = client.responses.create(
    model="gpt-5.2",
    input="Напиши короткое стихотворение о весне",
    instructions="Ты поэт, пишешь в классическом стиле. Используй рифму и метр."
)

Структура ответа

Ответ возвращается в виде структурированного объекта response:

{
  "id": "resp_1234567890",
  "object": "response",
  "model": "gpt-5.2",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [
        { "type": "output_text", "text": "...", "annotations": [] }
      ]
    }
  ],
  "usage": { "input_tokens": 12, "output_tokens": 45, "total_tokens": 57 },
  "status": "completed"
}

Удобнее всего брать готовый текст из response.output_text (в SDK) или из output[].content[].text (в сыром JSON).

Стриминг ответов

Для вывода в реальном времени добавьте stream: true:

stream = client.responses.create(
    model="gpt-5.2",
    input="Напиши короткий рассказ об ИИ",
    stream=True
)

for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)

Сервер отдаёт Server-Sent Events: response.created, response.output_text.delta, response.completed и [DONE] в конце.

Встроенный веб-поиск

Главное преимущество Responses API — веб-поиск в реальном времени через параметр plugins. Модель получает свежую информацию и возвращает её с цитатами-источниками:

response = client.responses.create(
    model="gpt-5.2",
    input="Какие главные новости в мире технологий на этой неделе?",
    extra_body={"plugins": [{"id": "web", "max_results": 5}]}
)

print(response.output_text)

В ответе появятся аннотации типа url_citation с полями url, start_index и end_index — по ним можно собрать список источников. Максимум — 10 результатов на запрос.

Режим рассуждений (reasoning)

Для сложных задач можно включить пошаговые рассуждения через параметр reasoning (для reasoning-моделей):

response = client.responses.create(
    model="o3",
    input="Спланируй стратегию выхода стартапа на рынок за 90 дней",
    reasoning={"effort": "high"}
)

print(response.output_text)

Веб-поиск и reasoning можно комбинировать в одном запросе.

Многоходовые диалоги (важно!)

Responses API не сохраняет состояние — каждый запрос независим. Чтобы модель помнила контекст, передавайте всю историю диалога в input массивом сообщений:

response = client.responses.create(
    model="gpt-5.2",
    input=[
        {"type": "message", "role": "user",
         "content": [{"type": "input_text", "text": "Какая столица Франции?"}]},
        {"type": "message", "role": "assistant", "id": "msg_1", "status": "completed",
         "content": [{"type": "output_text", "text": "Париж.", "annotations": []}]},
        {"type": "message", "role": "user",
         "content": [{"type": "input_text", "text": "А какое там население?"}]}
    ]
)

Для сообщений с ролью assistant в истории обязательны поля id и status.

Основные параметры

Когда выбирать Responses API

• Responses API — если нужен простой ввод, встроенный веб-поиск, инструменты и reasoning «из коробки».
• Chat Completions — если у вас уже есть рабочий код на messages и не нужны встроенные инструменты.

Доступ из России

OpenAI напрямую недоступен из России: блокировка по IP, нет оплаты российскими картами, VPN рискован. AITUNNEL решает это — тот же OpenAI SDK и Responses API, но:

• без VPN — стабильное соединение из РФ;
• оплата в рублях — карта МИР, СБП, для юрлиц по счёту;
• pay-as-you-go — платите только за использованные токены;
• минимальное пополнение от 399₽.

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

Responses API заменяет Chat Completions? Нет, оба API работают параллельно. Responses — более новый и удобный, но Chat Completions никуда не делся.

Хранит ли API историю диалога? Нет, API без состояния. Историю нужно передавать в каждом запросе самостоятельно.

Какие модели поддерживаются? Все актуальные модели OpenAI (GPT-5.2, GPT-4.1, o-серия) и другие модели через AITUNNEL.

Нужен ли отдельный ключ? Нет, используется тот же API-ключ AITUNNEL, что и для Chat Completions.