Skip to Content
APIПротокол совместимости с OpenAIResponses (Рекомендуется)

Responses API (Рекомендуется)

Создание ответов модели. Поддерживает текстовый и графический ввод, генерацию текста или JSON. Поддерживает вызов функций (Tool Calling), потоковые ответы и многоходовой диалог.

Для новых проектов рекомендуется использовать Responses API. Это API нового поколения от OpenAI, которое по сравнению с Chat Completions обладает следующими преимуществами:

  • Нативный Prompt Cachinginstructions отделены от input, системные инструкции автоматически используются как префикс кэша. В многоходовом диалоге неизменная часть префикса даёт более высокий процент попаданий в кэш, что позволяет экономить до 50% затрат на входные токены и одновременно снижает задержку
  • Структурированный режим item — формат ввода/вывода стал понятнее, нативная поддержка процесса вызова инструментов
  • Более богатые потоковые события — детализированные типы SSE-событий упрощают рендеринг UI в реальном времени

Эндпоинт

POST https://api.ofox.ai/v1/responses

Параметры запроса

ПараметрТипОбязателенОписание
modelstringИдентификатор модели, например openai/gpt-5.4-mini
inputstring | arrayСодержимое ввода: обычная текстовая строка или структурированный массив сообщений
instructionsstringСистемные инструкции (независимы от input, автоматически используют Prompt Caching)
streambooleanВключить ли потоковый ответ SSE, по умолчанию false
max_output_tokensnumberМаксимальное количество генерируемых токенов
temperaturenumberТемпература сэмплирования 0-2, по умолчанию 1
top_pnumberПараметр nucleus sampling
toolsarrayОпределения доступных инструментов (Function Calling)
tool_choicestring | objectСтратегия выбора инструмента: auto, none или указанный инструмент
truncationstringСтратегия усечения: auto — автоматическое усечение / disabled — ошибка при превышении лимита (по умолчанию)
textobjectКонфигурация формата генерации текста
storebooleanСохранять ли ответ (по умолчанию true)
metadataobjectПользовательские пары ключ-значение метаданных
providerobjectРасширение OfoxAI: конфигурация маршрутизации и аварийного переключения

Формат Input

input поддерживает два формата:

1. Простая строка — передаётся текст напрямую

{ "input": "Привет, расскажите о себе" }

2. Структурированный массив сообщений — многоходовой диалог и мультимодальный ввод

interface InputItem { type: 'message' role: 'user' | 'assistant' content: ContentPart[] id?: string // обязательно для сообщений assistant status?: 'completed' // обязательно для сообщений assistant } type ContentPart = | { type: 'input_text'; text: string } // текстовый ввод пользователя | { type: 'input_image'; image_url: string } // графический ввод | { type: 'output_text'; text: string; annotations?: any[] } // текстовый вывод ассистента

При включении сообщений с ролью assistant в многоходовом диалоге поля id и status обязательны. Responses API спроектирован как stateless, каждый запрос должен содержать полную историю диалога.

Примеры запросов

Terminal
curl https://api.ofox.ai/v1/responses \ -H "Authorization: Bearer $OFOX_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "openai/gpt-5.4-mini", "input": "Объясните, что такое API Gateway", "instructions": "Вы — полезный технический ассистент, отвечайте на русском языке.", "max_output_tokens": 1024 }'

Формат ответа

{ "id": "resp_abc123", "object": "response", "created_at": 1703123456, "model": "openai/gpt-5.4-mini", "status": "completed", "output": [ { "type": "message", "id": "msg_def456", "status": "completed", "role": "assistant", "content": [ { "type": "output_text", "text": "API Gateway (API-шлюз) — это...", "annotations": [] } ] } ], "usage": { "input_tokens": 25, "output_tokens": 150, "total_tokens": 175 } }

Описание полей ответа

ПолеТипОписание
idstringУникальный идентификатор ответа, начинается с resp_
objectstringФиксированное значение "response"
created_atnumberВременная метка создания (Unix, в секундах)
modelstringID фактически использованной модели
statusstringСтатус ответа: completed, failed, in_progress, cancelled
outputarrayМассив output item, содержит сообщения и вызовы инструментов
usageobjectСтатистика использования токенов

Структурированный ввод сообщений

Используйте структурированный массив сообщений для реализации многоходового диалога:

multi_turn.py
response = client.responses.create( model="openai/gpt-5.4-mini", input=[ { "type": "message", "role": "user", "content": [ {"type": "input_text", "text": "Какая столица Франции?"} ] }, { "type": "message", "role": "assistant", "id": "msg_abc123", "status": "completed", "content": [ {"type": "output_text", "text": "Столица Франции — Париж.", "annotations": []} ] }, { "type": "message", "role": "user", "content": [ {"type": "input_text", "text": "Сколько там жителей?"} ] } ] ) print(response.output_text)

Потоковые ответы

Установите stream: true для включения потокового ответа SSE:

stream.py
stream = client.responses.create( model="openai/gpt-5.4-mini", input="Расскажите шутку про программирование", stream=True ) for event in stream: if event.type == "response.output_text.delta": print(event.delta, end="", flush=True)

Типы потоковых событий

Потоковый ответ через SSE отправляет следующие события:

data: {"type":"response.created","response":{"id":"resp_abc123","object":"response","status":"in_progress"}} data: {"type":"response.output_item.added","output_index":0,"item":{"type":"message","id":"msg_def456","role":"assistant","status":"in_progress","content":[]}} data: {"type":"response.content_part.added","output_index":0,"content_index":0,"part":{"type":"output_text","text":""}} data: {"type":"response.output_text.delta","output_index":0,"content_index":0,"delta":"При"} data: {"type":"response.output_text.delta","output_index":0,"content_index":0,"delta":"вет"} data: {"type":"response.output_item.done","output_index":0,"item":{"type":"message","id":"msg_def456","role":"assistant","status":"completed","content":[{"type":"output_text","text":"Привет..."}]}} data: {"type":"response.completed","response":{"id":"resp_abc123","object":"response","status":"completed","usage":{"input_tokens":12,"output_tokens":45,"total_tokens":57}}} data: [DONE]
Тип событияОписание
response.createdОбъект ответа создан
response.output_item.addedДобавлен новый output item
response.content_part.addedДобавлен новый фрагмент контента
response.output_text.deltaИнкремент текста (вывод по токенам)
response.output_item.doneOutput item завершён
response.completedОтвет полностью завершён
response.function_call_arguments.deltaИнкремент аргументов вызова функции
response.function_call_arguments.doneАргументы вызова функции завершены

Function Calling

Responses API нативно поддерживает вызов инструментов:

tools.py
response = client.responses.create( model="openai/gpt-5.4-mini", input="Какая сегодня погода в Москве?", tools=[ { "type": "function", "name": "get_weather", "description": "Получить текущую погоду в указанном городе", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "Название города, например Москва" }, "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] } }, "required": ["location"] } } ], tool_choice="auto" ) # Обработка вызова инструмента for item in response.output: if item.type == "function_call": print(f"Вызов функции: {item.name}") print(f"Аргументы: {item.arguments}")

Формат ответа при вызове инструмента

Когда модель вызывает инструмент, в output появляется item типа function_call:

{ "id": "resp_abc123", "object": "response", "status": "completed", "output": [ { "type": "function_call", "id": "fc_abc123", "call_id": "call_xyz789", "name": "get_weather", "arguments": "{\"location\":\"Москва\",\"unit\":\"celsius\"}" } ], "usage": { "input_tokens": 45, "output_tokens": 25, "total_tokens": 70 } }

Передача результатов инструмента

Передайте результаты выполнения инструмента обратно модели, включив полную цепочку вызовов в input:

# Второй запрос: передача результатов инструмента response = client.responses.create( model="openai/gpt-5.4-mini", input=[ { "type": "message", "role": "user", "content": [{"type": "input_text", "text": "Какая сегодня погода в Москве?"}] }, { "type": "function_call", "id": "fc_abc123", "call_id": "call_xyz789", "name": "get_weather", "arguments": "{\"location\":\"Москва\",\"unit\":\"celsius\"}" }, { "type": "function_call_output", "id": "fco_abc123", "call_id": "call_xyz789", "output": "{\"temperature\":\"22°C\",\"condition\":\"ясно\"}" } ] ) print(response.output_text) # => "Сегодня в Москве ясно, температура 22°C, отличная погода для прогулки."

Варианты Tool Choice

ЗначениеОписание
"auto"Модель сама решает, вызывать ли инструмент (по умолчанию)
"none"Запретить вызов инструментов
{"type": "function", "name": "tool_name"}Принудительный вызов указанного инструмента

Сравнение с Chat Completions

ХарактеристикаChat CompletionsResponses API
Эндпоинт/v1/chat/completions/v1/responses
Формат вводаМассив messagesСтрока input или структурированный массив item
Системные инструкцииСообщение role: "system"Параметр instructions (независимое кэширование)
Prompt CachingСистемные инструкции смешаны с messages, префикс кэша нестабиленinstructions передаётся отдельно, автоматическое кэширование, более высокий процент попаданий
Формат выводаchoices[0].message.contentoutput[0].content[0].text или output_text
Вызов инструментовtool_calls внутри messageОтдельный output item function_call
Результаты инструментовСообщение role: "tool"Input item function_call_output
Потоковые событияchat.completion.chunkСтруктурированные типы событий (response.*)
Поля токеновprompt_tokens / completion_tokensinput_tokens / output_tokens

Оба API подходят для продакшена. Если у вас уже есть интеграция с Chat Completions, мигрировать не нужно. Для новых проектов рекомендуется Responses API, особенно в сценариях со сложными процессами вызова инструментов или высокочастотными запросами (можно полноценно использовать кэширование для снижения затрат). Подробнее в Руководстве по вызову функций.

Last updated on