Skip to main content
POST
Создать response (Responses API)

О Responses API

Responses API находится в бета-версии. API может измениться без предварительного уведомления.
Responses API — формат, совместимый с OpenAI Responses API. Работает с официальным OpenAI SDK (client.responses.create(...)), Codex CLI и другими каноничными клиентами. Внутри запрос трансформируется в Chat Completions и уходит выбранному провайдеру. Эндпоинты: Пути /v2/responses и /v2/responses/compact — алиасы, поведение идентично.
API stateless. Мы не храним предыдущие ответы: previous_response_id, conversation и store не поддерживаются. Всю историю диалога — включая вызовы инструментов — передавайте в input каждым запросом. Методов GET /v1/responses/{id}, DELETE и /cancel нет.

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

Alias-формат модели

К имени модели можно дописать параметры маршрутизации через @:
Поддерживаемые ключи: provider, reasoning_effort, allow_fallbacks. При конфликте alias и одноимённого поля в теле запроса API вернёт 400.

Дополнительные параметры

Не поддерживаются

Эти поля принимаются ради совместимости с OpenAI SDK, но не влияют на результат:

Примеры

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

status — completed, incomplete или failed. При incomplete заполняется incomplete_details.reason (max_output_tokens или content_filter). В usage поля продублированы в двух неймингах: input_tokens/output_tokens (Responses API) и prompt_tokens/completion_tokens (Chat Completions) — используйте любой. cost_rub — фактическая стоимость запроса, списанная с баланса.

Tool calling

Поддерживается полный цикл: передача tools → получение function_call → отправка результата через function_call_output → финальный ответ модели.

Типы инструментов

Возможность вызывать инструменты зависит от модели. Если модель не поддерживает tool calling, инструменты будут проигнорированы провайдером. Проверяйте поддержку в каталоге моделей.

1. Запрос с инструментами

2. Ответ с вызовом инструмента

3. Возврат результата инструмента

Выполните функцию на своей стороне и отправьте новый запрос со всей историей: исходное сообщение пользователя, item function_call и item function_call_output с тем же call_id.
В поле tools второго запроса передайте те же определения инструментов, что и в первом.
Item function_call обязателен. Если прислать только function_call_output — например, рассчитывая, что историю подтянет previous_response_id, — модель получит результат инструмента без самого вызова и вернёт ошибку вида messages with role 'tool' must be a response to a preceding message with 'tool_calls'. API stateless, историю нужно передавать полностью.

Типы input items

Мультимодальный input

В content сообщения можно передать массив частей:

Streaming

При stream: true ответ приходит в формате SSE. Имена и порядок событий соответствуют спецификации OpenAI Responses API, поэтому работают официальный OpenAI SDK и Codex CLI.

События

Типовой порядок событий для текстового ответа:
Для вызова инструмента:
Источник истины для запуска инструмента — событие response.output_item.done с item.type = "function_call": в нём полные name, arguments и call_id.

Особенности

  • Каждое событие несёт монотонный sequence_number — используйте его для упорядочивания.
  • Стрим завершается строкой data: [DONE]. Она нужна ChatCompletion-подобным клиентам, каноничные клиенты Responses API её игнорируют.
  • При долгом ожидании ответа провайдера сервер шлёт SSE-комментарии : processing — игнорируйте строки, начинающиеся с :.
  • Если модель вызывает несколько инструментов параллельно, у каждого свой output_index.
  • При ошибке посреди стрима приходит терминальное response.failed, стрим не обрывается молча.
cURL

Компактизация истории

POST /v1/responses/compact укорачивает историю диалога, когда она перестаёт помещаться в контекст. Полезно агентским клиентам с длинными сессиями. Сервер сохраняет все инструкции (system и developer), последние keep_last сообщений и все структурные items (function_call, function_call_output, reasoning), а вытесненные текстовые сообщения сворачивает в один summary-плейсхолдер. Обращения к модели не происходит — метод бесплатный и синхронный.
В input передайте полную историю input items. Ответ содержит укороченную историю, которую нужно передать в следующий POST /v1/responses:
Значение keep_last по умолчанию — 6.

Следующие шаги

Вызов функций

Tool calling в формате Chat Completions

Codex CLI

Подключение Codex CLI к Polza.ai

Структурный вывод

JSON Schema и строгие форматы ответа

Выбор провайдера

Маршрутизация и fallback

Авторизации

Authorization
string
header
обязательно

API ключ передаётся в заголовке: Authorization: Bearer <POLZA_AI_API_KEY>

Тело

application/json
input
обязательно

Input for response - can be string or array of input items

Пример:

"Hello, how are you?"

model
string
обязательно

Идентификатор модели. Для Responses API поддерживается alias-формат @=&=. Поддерживаемые ключи: provider, reasoning_effort, allow_fallbacks, data_residency. При конфликте alias и обычных полей body API возвращает 400. Для некоторых провайдеров и моделей допустимые значения reasoning_effort отличаются; например, Yandex AI Studio поддерживает только low, medium и high.

Пример:

"openai/gpt-4o@provider=google&reasoning_effort=high&allow_fallbacks=false"

instructions
string

System instructions

Пример:

"You are a helpful assistant"

metadata
object

Metadata key-value pairs

tools
any · object · object · any · any · any · object[]

Tools available for the model

tool_choice

Tool choice strategy

Доступные опции:
none,
auto,
required
Пример:

"auto"

parallel_tool_calls
boolean
по умолчанию:false

Enable parallel tool calls

background
boolean
устарело

Запуск response в background-режиме OpenAI. В Polza provider path не запускает отдельную async job и игнорируется.

include
string[]

Дополнительные поля output, которые OpenAI может включить в ответ. Поддерживается как входной параметр совместимости; конкретные include зависят от провайдера.

Пример:
models
string[]
устарело

НЕ РЕАЛИЗОВАНО. Массив fallback-моделей пока не поддерживается Responses API и игнорируется. Для fallback используйте alias-формат в model: @allow_fallbacks=true.

text
object

Text output configuration

reasoning
object

Reasoning configuration

max_output_tokens
number

Maximum output tokens

Пример:

1000

temperature
number

Temperature (0-2)

Требуемый диапазон: 0 <= x <= 2
Пример:

0.7

top_p
number

Top P (nucleus sampling)

Требуемый диапазон: 0 <= x <= 1
Пример:

1

top_logprobs
number

Top logprobs

Требуемый диапазон: 0 <= x <= 20
Пример:

5

max_tool_calls
number

Максимум вызовов серверных инструментов за запрос (по умолчанию 10, потолок 30; без polza:* — лимит вызовов провайдера)

Пример:

5

stop_server_tools_when
object[]

Условия остановки цикла серверных инструментов: step_count заменяет max_tool_calls (потолок 30), spend_cap добавляет мягкий потолок расходов на запрос: он проверяется перед каждым шагом модели, поэтому итог может превысить spend_cap на шаг, на котором потолок пройден, его инструменты и финальный ответ

prompt
object
устарело

Конфигурация reusable prompt OpenAI. В текущем provider path Polza не загружает prompt templates и игнорирует поле.

presence_penalty
number

Presence penalty (-2 to 2)

Требуемый диапазон: -2 <= x <= 2
frequency_penalty
number

Frequency penalty (-2 to 2)

Требуемый диапазон: -2 <= x <= 2
top_k
number

Top K sampling

Пример:

40

image_config
object

Image configuration options

modalities
enum<string>[]

Output modalities

Доступные опции:
text,
image
prompt_cache_key
string

Prompt cache key

prompt_cache_retention
enum<string>

Prompt cache retention policy

Доступные опции:
in_memory,
24h
previous_response_id
string
устарело

НЕ РЕАЛИЗОВАНО. Продолжение по previous_response_id пока не поддерживается и игнорируется. Для мультитёрн-сессий передавайте историю целиком в input.

conversation
object
устарело

Conversation ID/object OpenAI Responses API. В Polza stateless path не подтягивает историю по conversation; передавайте историю целиком в input.

context_management
array

Context management OpenAI Responses API. Локальная компактизация доступна через /v1/responses/compact; поле принимается для совместимости.

moderation
object

Input/output moderation configuration

stream
boolean
по умолчанию:false

Enable streaming

stream_options
object

Опции стриминга

provider
object

Provider preferences

user
string

Уникальный идентификатор конечного пользователя для отслеживания и предотвращения злоупотреблений

Пример:

"user-123"

safety_identifier
string

Stable hashed end-user identifier from OpenAI Responses API. Если user не указан, используется как user для downstream provider.

Пример:

"sha256-user-id"

service_tier
enum<string>

OpenAI service tier

Доступные опции:
auto,
default,
flex,
scale,
priority
store
boolean

Whether to store generated response for later retrieval

truncation
enum<string>

Truncation strategy

Доступные опции:
auto,
disabled
session_id
string
устарело

НЕ РЕАЛИЗОВАНО. session_id не пробрасывается провайдеру (OpenRouter Chat Completions API не поддерживает это поле) и игнорируется. Для отслеживания сессий используйте metadata или user.

plugins
string[]

Плагины для расширения функциональности (web search, file parser и др.)

Ответ

id
string
обязательно

Response ID

Пример:

"gen_581761234567890123"

object
enum<string>
обязательно
Доступные опции:
response
Пример:

"response"

created_at
number
обязательно

Created timestamp

Пример:

1234567890

model
string
обязательно

Model used

Пример:

"openai/gpt-4"

status
enum<string>
обязательно
Доступные опции:
completed,
incomplete,
in_progress,
failed,
cancelled,
queued
Пример:

"completed"

output_text
string
обязательно

Full output text (convenience field)

Пример:

"Hello! How can I help you today?"

output
array
обязательно

Output items array

completed_at
object | null

Completed timestamp

error
object | null

Error information

incomplete_details
object | null

Details about incomplete response

usage
object

Usage information

metadata
object

Metadata key-value pairs

polza
object

Есть, если модель вызывала серверные инструменты: parent_generation_id — id запроса в истории (GET /v1/history/generations/{id}), шаги — /children