Responses API (Рекомендуется)
Создание ответов модели. Поддерживает текстовый и графический ввод, генерацию текста или JSON. Поддерживает вызов функций (Tool Calling), потоковые ответы и многоходовой диалог.
Для новых проектов рекомендуется использовать Responses API. Это API нового поколения от OpenAI, которое по сравнению с Chat Completions обладает следующими преимуществами:
- Нативный Prompt Caching —
instructionsотделены отinput, системные инструкции автоматически используются как префикс кэша. В многоходовом диалоге неизменная часть префикса даёт более высокий процент попаданий в кэш, что позволяет экономить до 50% затрат на входные токены и одновременно снижает задержку - Структурированный режим item — формат ввода/вывода стал понятнее, нативная поддержка процесса вызова инструментов
- Более богатые потоковые события — детализированные типы SSE-событий упрощают рендеринг UI в реальном времени
Эндпоинт
POST https://api.ofox.ai/v1/responsesПараметры запроса
| Параметр | Тип | Обязателен | Описание |
|---|---|---|---|
model | string | ✅ | Идентификатор модели, например openai/gpt-5.4-mini |
input | string | array | ✅ | Содержимое ввода: обычная текстовая строка или структурированный массив сообщений |
instructions | string | — | Системные инструкции (независимы от input, автоматически используют Prompt Caching) |
stream | boolean | — | Включить ли потоковый ответ SSE, по умолчанию false |
max_output_tokens | number | — | Максимальное количество генерируемых токенов |
temperature | number | — | Температура сэмплирования 0-2, по умолчанию 1 |
top_p | number | — | Параметр nucleus sampling |
tools | array | — | Определения доступных инструментов (Function Calling) |
tool_choice | string | object | — | Стратегия выбора инструмента: auto, none или указанный инструмент |
truncation | string | — | Стратегия усечения: auto — автоматическое усечение / disabled — ошибка при превышении лимита (по умолчанию) |
text | object | — | Конфигурация формата генерации текста |
store | boolean | — | Сохранять ли ответ (по умолчанию true) |
metadata | object | — | Пользовательские пары ключ-значение метаданных |
provider | object | — | Расширение 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, каждый запрос должен содержать полную историю диалога.
Примеры запросов
cURL
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
}
}Описание полей ответа
| Поле | Тип | Описание |
|---|---|---|
id | string | Уникальный идентификатор ответа, начинается с resp_ |
object | string | Фиксированное значение "response" |
created_at | number | Временная метка создания (Unix, в секундах) |
model | string | ID фактически использованной модели |
status | string | Статус ответа: completed, failed, in_progress, cancelled |
output | array | Массив output item, содержит сообщения и вызовы инструментов |
usage | object | Статистика использования токенов |
Структурированный ввод сообщений
Используйте структурированный массив сообщений для реализации многоходового диалога:
Python
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:
Python
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.done | Output item завершён |
response.completed | Ответ полностью завершён |
response.function_call_arguments.delta | Инкремент аргументов вызова функции |
response.function_call_arguments.done | Аргументы вызова функции завершены |
Function Calling
Responses API нативно поддерживает вызов инструментов:
Python
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 Completions | Responses API |
|---|---|---|
| Эндпоинт | /v1/chat/completions | /v1/responses |
| Формат ввода | Массив messages | Строка input или структурированный массив item |
| Системные инструкции | Сообщение role: "system" | Параметр instructions (независимое кэширование) |
| Prompt Caching | Системные инструкции смешаны с messages, префикс кэша нестабилен | instructions передаётся отдельно, автоматическое кэширование, более высокий процент попаданий |
| Формат вывода | choices[0].message.content | output[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_tokens | input_tokens / output_tokens |
Оба API подходят для продакшена. Если у вас уже есть интеграция с Chat Completions, мигрировать не нужно. Для новых проектов рекомендуется Responses API, особенно в сценариях со сложными процессами вызова инструментов или высокочастотными запросами (можно полноценно использовать кэширование для снижения затрат). Подробнее в Руководстве по вызову функций.