OpenAI Responses

Создавайте ответы с текстом, изображениями, вызовами инструментов и рассуждением через API, совместимый с OpenAI Responses.

API Responses использует Typed Items для единого представления текста, изображений, файлов, вызовов инструментов и результатов рассуждения. Он подходит приложениям с мультимодальным вводом, встроенными инструментами, взаимодействием с состоянием или семантическими потоковыми событиями. Доступные типы Item, инструменты и расширенные поля могут различаться между моделями; ориентируйтесь на модели, доступные текущему аккаунту, и результаты фактических вызовов.

POST/v1/responses

Создаёт ответ модели на основе текста, изображений, файлов или Typed Input Items. API может возвращать разные типы Output Items, включая сообщения, элементы рассуждения и вызовы инструментов, и поддерживает передачу семантических событий через SSE.

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

Аутентификация

bearerAuth

АутентификацияBearer <token>

Используйте Bearer your-api-key в Header Authorization.

Расположение: header

Тело запроса

Responses использует Typed Items для ввода, инструментов и вывода. Выберите представление по задаче; применение полей зависит от модели и канала.

application/json

Текстовый ввод

Самый простой способ — передать строку в input; можно также использовать Typed Items в форме сообщений.

model: ID модели, доступной текущему ключу API и поддерживающей Responses.
input: Строка или массив Typed Input Items.
instructions: Высокоуровневые инструкции только для текущего ответа.

application/json

{
  "model": "MODEL_ID",
  "input": "Представьтесь в трёх предложениях."
}

Простой текстовый ответ. input может быть строкой или Typed Input Items.

background?boolean|null

Выполнять ли ответ в фоновом режиме. Доступность зависит от модели, канала и прав аккаунта.

По умолчаниюfalse

context_management?array<>|null

Настройки управления контекстом текущего запроса, например сжатие при достижении заданного порога токенов.

conversation?string||null

Conversation, к которой относится ответ. Можно передать ID Conversation или объект с id; нельзя использовать вместе с previous_response_id.

model?string

ID текстовой модели Responses. Выберите модель, доступную текущему ключу API.

Длина1 <= length

input?text input|array<||||||||||||||||||||||||||||||>

Текстовый ввод: строка, сообщения или другие Typed Items.

include?array<>|null

Дополнительные данные, которые следует включить в ответ.

instructions?string|array<||||||||||||||||||||||||||||||>|null

Системное сообщение или сообщение разработчика с высокоуровневыми инструкциями для этого ответа. При использовании previous_response_id поле instructions предыдущего ответа автоматически не наследуется.

max_output_tokens?integer|null

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

max_tool_calls?integer|null

Общий предел вызовов встроенных инструментов для этого ответа, а не отдельный предел для каждого типа инструмента.

Диапазон0 <= value

metadata?|null

Пары ключ–значение, прикреплённые к объекту ответа. Ключ — до 64 символов, значение — до 512 символов.

Поляproperties <= 16

parallel_tool_calls?boolean|null

Разрешать ли модели параллельные вызовы инструментов.

По умолчаниюtrue

moderation?|null

Настройки модерации входных и выходных данных ответа.

previous_response_id?string|null

Уникальный ID предыдущего Response для продолжения взаимодействия с состоянием. Нельзя использовать вместе с conversation; instructions предыдущего ответа автоматически не наследуется.

prompt?|null

Ссылка на сохранённый шаблон Prompt и его переменные.

prompt_cache_key?string|null

Повышает частоту попаданий в кэш промпта для похожих запросов и заменяет использование user для кэширования.

prompt_cache_options?|null

Настройки кэша промпта на уровне запроса. Блоки содержимого могут отмечать явные границы кэша через prompt_cache_breakpoint.

prompt_cache_retention?string|null

Устарело

Устарело; используйте prompt_cache_options.ttl. Поле сохранено для совместимости с прежней стратегией хранения кэша.

Допустимые значения

"in_memory"
"24h"
null

reasoning?|null

Настройки модели рассуждения. Применимы только к моделям с поддержкой этой возможности.

service_tier?string|null

Запрашиваемый уровень обслуживания. Фактическое значение в ответе может отличаться: например, для запроса fast может вернуться priority.

По умолчанию"auto"

Допустимые значения

"auto"
"default"
"flex"
"scale"
"priority"
"fast"
"ultrafast"
null

safety_identifier?string|null

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

Длинаlength <= 64

store?boolean|null

Сохранять ли сгенерированный ответ. Хранение, чтение и срок хранения зависят от возможностей платформы.

По умолчаниюtrue

stream?boolean|null

При true возвращает семантические события Responses через Server-Sent Events.

По умолчаниюfalse

stream_options?|null

Настройки потокового ответа. Используются только при stream равном true.

temperature?number|null

Температура выборки. Обычно изменяют только temperature или top_p.

Диапазон0 <= value <= 2

По умолчанию1

text?

tool_choice?||||||||

Управляет тем, выбирает ли модель инструменты и как именно.

tools?array<|||||||||||||>

Встроенные инструменты или пользовательские функции, доступные модели. Поддержка зависит от модели и канала.

top_logprobs?integer|null

Количество наиболее вероятных кандидатов для каждой позиции выходного токена: от 0 до 20.

Диапазон0 <= value <= 20

top_p?number|null

Вероятностная масса ядерной выборки. Обычно изменяют только top_p или temperature.

Диапазон0 <= value <= 1

По умолчанию1

truncation?string|null

Устарело

Стратегия усечения при превышении окна контекста. disabled приводит к ошибке запроса сверх лимита.

По умолчанию"disabled"

Допустимые значения

"auto"
"disabled"
null

user?string

Устарело

Устарело. Для безопасности используйте safety_identifier, для группировки кэша — prompt_cache_key.

Инструменты, состояние, рассуждение и мультимодальные возможности Responses зависят от модели и канала поставщика. Начните с минимального текстового запроса, затем включайте расширенные поля по одному.

Тело ответа

`application/json`

curl -X POST "https://example.com/v1/responses" \  -H "Content-Type: application/json" \  -d '{    "model": "MODEL_ID",    "input": "Расскажите в трёх предложениях сказку на ночь о единороге."  }'

{
  "id": "resp_example",
  "object": "response",
  "created_at": 1741476542,
  "status": "completed",
  "error": null,
  "incomplete_details": null,
  "instructions": null,
  "max_output_tokens": null,
  "model": "MODEL_ID",
  "output": [
    {
      "id": "msg_example",
      "type": "message",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Под лунным светом единорог обнаружил тайную тропинку к звёздному небу.",
          "annotations": []
        }
      ]
    }
  ],
  "parallel_tool_calls": true,
  "previous_response_id": null,
  "reasoning": {
    "effort": null,
    "summary": null
  },
  "store": true,
  "temperature": 1,
  "text": {
    "format": {
      "type": "text"
    }
  },
  "tool_choice": "auto",
  "tools": [],
  "top_p": 1,
  "truncation": "disabled",
  "usage": {
    "input_tokens": 18,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 22,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 40
  },
  "user": null,
  "metadata": {}
}

Официальная документация OpenAI ResponsesОпределение протокола поставщика и последние изменения полей.

Аутентификация

Тело запроса

Тело ответа

200application/json

400application/json

401application/json

403application/json

404application/json

429application/json

500application/json

502application/json

503application/json

504application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`