POST

/v1/responses

Справочник API

Responses API — формат OpenAI, который используют Codex CLI и OpenAI Agents SDK.

Работает с моделями claude-* и gpt-*. Модели GLM поля input и instructions не понимают — для них используйте /v1/chat/completions или /v1/messages.

Эндпоинт

bash

POST https://api.zukko.pro/v1/responses

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

Формат

Заголовок

Bearer

Authorization: Bearer fetch_...

x-api-key

x-api-key: fetch_...

Ключ в query string не принимается.

Поддерживаемые параметры

Параметр

Тип

Описание

model

string

Обязательный. Название модели или алиас

input

string или array

Ввод — строка или массив сообщений/tool-вызовов

instructions

string

Системный промпт

stream

boolean

SSE-стриминг (по умолчанию: false)

max_output_tokens

integer

Максимум токенов в ответе

temperature

number

Температура сэмплирования

top_p

number

Nucleus sampling

tools

array

Функции в формате Responses API

tool_choice

string или object

Стратегия выбора инструмента

parallel_tool_calls

boolean

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

reasoning

object

{"effort": "low" / "medium" / "high"}

truncation

string

Стратегия обрезки

previous_response_id

string

Игнорируется (stateless proxy)

store

boolean

Игнорируется (stateless proxy)

Формат input

Поле input принимает три формата:

Простая строка:

JSON

bash

{
  "model": "claude-sonnet-5",
  "input": "Объясни квантовые вычисления простыми словами"
}

Массив сообщений:

JSON

bash

{
  "model": "gpt-5.6-sol",
  "input": [
    {
      "type": "message",
      "role": "user",
      "content": [
        {"type": "input_text", "text": "Что на этом изображении?"},
        {"type": "input_image", "image_url": "https://example.com/photo.jpg"}
      ]
    }
  ]
}

Многоходовый диалог с tool calls:

JSON

bash

{
  "model": "claude-sonnet-5",
  "input": [
    {"type": "message", "role": "user", "content": "Какая погода в Москве?"},
    {"type": "function_call", "call_id": "call_1", "name": "get_weather", "arguments": "{\"city\":\"Moscow\"}"},
    {"type": "function_call_output", "call_id": "call_1", "output": "{\"temp\": 18, \"condition\": \"облачно\"}"},
    {"type": "message", "role": "user", "content": "А в Лондоне?"}
  ]
}

Инструменты (Tools)

Инструменты в формате Responses API с type: "function":

JSON

bash

{
  "tools": [
    {
      "type": "function",
      "name": "get_weather",
      "description": "Получить текущую погоду",
      "parameters": {
        "type": "object",
        "properties": {
          "city": {"type": "string"}
        },
        "required": ["city"]
      }
    }
  ]
}

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

Не-стриминговые ответы возвращают объект response:

JSON

bash

{
  "id": "resp_chatcmpl-abc123",
  "object": "response",
  "created_at": 1715500000,
  "model": "claude-sonnet-5",
  "status": "completed",
  "output": [
    {
      "id": "msg_chatcmpl-abc123",
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [
        {"type": "output_text", "text": "Вот мой ответ..."}

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

JSON

bash

{
  "output": [
    {
      "id": "call_1",
      "type": "function_call",
      "call_id": "call_1",
      "name": "get_weather",
      "arguments": "{\"city\":\"Moscow\"}",
      "status": "completed"
    }
  ]
}

Reasoning (при установленном reasoning.effort):

JSON

bash

{
  "output": [
    {"id": "rs_abc", "type": "reasoning", "summary": []},
    {
      "type": "message",
      "content": [{"type": "output_text", "text": "После тщательного анализа..."}]
    }
  ]
}

Стриминг

Установите "stream": true для получения Server-Sent Events:

bash

event: response.created
data: {"type":"response.created","response":{"id":"resp_...","status":"in_progress"}}

event: response.output_item.added
data: {"type":"response.output_item.added","output_index":0,"item":{"type":"message"}}

event: response.content_part.added
data: {"type":"response.content_part.added","output_index":0,"content_index":0}

event: response.output_text.delta
data: {"type":"response.output_text.delta","output_index":0,"content_index":0,"delta":"Привет"}

event: response.content_part.done
data: {"type":"response.content_part.done","output_index":0,"content_index":0}

event: response.output_item.done
data: {"type":"response.output_item.done","output_index":0}

event: response.completed
data: {"type":"response.completed","response":{"id":"resp_...","status":"completed"}}

Стриминг вызовов инструментов:

response.output_item.added — элемент function_call
response.function_call_arguments.delta — фрагменты аргументов
response.function_call_arguments.done — аргументы завершены
response.output_item.done — вызов завершён

Стриминг reasoning:

response.output_item.added — элемент reasoning
response.reasoning_text.delta — фрагменты размышлений

Использование с Codex CLI

Bash

bash

export OPENAI_BASE_URL=https://api.zukko.pro/v1
export OPENAI_API_KEY=fetch_ваш_ключ
codex -m gpt-5.6-sol

Для постоянной настройки пропишите провайдера в ~/.codex/config.toml — см. гайд Codex.

Claude Code

Claude Code работает не через Responses API, а через POST /v1/messages. Ему нужен Anthropic base URL без /v1 и ключ в ANTHROPIC_AUTH_TOKEN:

Bash

bash

export ANTHROPIC_BASE_URL=https://api.zukko.pro
export ANTHROPIC_AUTH_TOKEN=fetch_ваш_ключ
claude

Полная настройка — в гайде Claude Code.

Использование с OpenAI SDK

Python

bash

from openai import OpenAI

client = OpenAI(
    api_key="fetch_ваш_ключ",
    base_url="https://api.zukko.pro/v1"
)

response = client.responses.create(
    model="claude-sonnet-5",
    input="Напиши хайку о программировании"
)

print(response.output_text)

Формат ошибок

Ошибки в формате OpenAI: error.message, error.type, error.code и error.param. Разбирайте их по code — текст ошибок Zukko на русском.

JSON

bash

{
  "error": {
    "message": "Модель 'gpt-5.4' снята с обслуживания. Используйте 'gpt-5.6-sol' — актуальный список: GET /v1/models. Поддержка — https://t.me/zukkopro?direct, напишите, пожалуйста.",
    "type": "invalid_request_error",
    "code": "model_retired",
    "param": "model"
  }
}

Частые ошибки: 401 — неверный API-ключ; 402 insufficient_balance — на балансе меньше $0.01; 403 — email не подтверждён или модель запрещена для ключа; 503 model_disabled — модель выключена. Собственного ограничения частоты запросов у Zukko нет: его 429 — это только лимиты ключа (key_daily_limit_reached, key_monthly_limit_reached), остальные 429 приходят от провайдера модели.

Лимиты ключа, идемпотентность и кэш

POST /v1/web-search