Zukko
zukko
RULog inGet a key
DocsPOST /v1/responses
POST

/v1/responses

API reference

The Responses API is the OpenAI format used by Codex CLI and the OpenAI Agents SDK.

Works with claude-* and gpt-* models. GLM models do not understand the input and instructions fields — use /v1/chat/completions or /v1/messages for them.

Endpoint

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

Authentication

Format
Header
Bearer
Authorization: Bearer fetch_...
x-api-key
x-api-key: fetch_...

A key in the query string is not accepted.

Supported parameters

Parameter
Type
Description
model
string
Required. Model name or alias
input
string or array
Input — a string or an array of messages/tool calls
instructions
string
System prompt
stream
boolean
SSE streaming (default: false)
max_output_tokens
integer
Maximum tokens in the response
temperature
number
Sampling temperature
top_p
number
Nucleus sampling
tools
array
Functions in the Responses API format
tool_choice
string or object
Tool selection strategy
parallel_tool_calls
boolean
Parallel tool calls
reasoning
object
{"effort": "low" / "medium" / "high"}
truncation
string
Truncation strategy
previous_response_id
string
Ignored (stateless proxy)
store
boolean
Ignored (stateless proxy)

input format

The input field accepts three formats:

A plain string:

JSON
bash
{
  "model": "claude-sonnet-5",
  "input": "Explain quantum computing in simple terms"
}

An array of messages:

JSON
bash
{
  "model": "gpt-5.6-sol",
  "input": [
    {
      "type": "message",
      "role": "user",
      "content": [
        {"type": "input_text", "text": "What is in this image?"},
        {"type": "input_image", "image_url": "https://example.com/photo.jpg"}
      ]
    }
  ]
}

A multi-turn conversation with tool calls:

JSON
bash
{
  "model": "claude-sonnet-5",
  "input": [
    {"type": "message", "role": "user", "content": "What's the weather in Moscow?"},
    {"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\": \"cloudy\"}"},
    {"type": "message", "role": "user", "content": "And in London?"}
  ]
}

Tools

Tools in the Responses API format with type: "function":

JSON
bash
{
  "tools": [
    {
      "type": "function",
      "name": "get_weather",
      "description": "Get the current weather",
      "parameters": {
        "type": "object",
        "properties": {
          "city": {"type": "string"}
        },
        "required": ["city"]
      }
    }
  ]
}

Response format

Non-streaming requests return a response object:

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": "Here is my answer..."}

A response containing a tool call:

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

Reasoning (when reasoning.effort is set):

JSON
bash
{
  "output": [
    {"id": "rs_abc", "type": "reasoning", "summary": []},
    {
      "type": "message",
      "content": [{"type": "output_text", "text": "After careful analysis..."}]
    }
  ]
}

Streaming

Set "stream": true to receive 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":"Hello"}

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"}}

Streaming tool calls:

  • response.output_item.added — function_call item
  • response.function_call_arguments.delta — argument chunks
  • response.function_call_arguments.done — arguments complete
  • response.output_item.done — call complete

Streaming reasoning:

  • response.output_item.added — reasoning item
  • response.reasoning_text.delta — reasoning text chunks

Using with Codex CLI

Bash
bash
export OPENAI_BASE_URL=https://api.zukko.pro/v1
export OPENAI_API_KEY=fetch_your_key
codex -m gpt-5.6-sol

For a permanent setup, configure the provider in ~/.codex/config.toml — see the Codex guide.

Claude Code

Claude Code does not use the Responses API; it works through POST /v1/messages. It needs the Anthropic base URL without /v1 and the key in ANTHROPIC_AUTH_TOKEN:

Bash
bash
export ANTHROPIC_BASE_URL=https://api.zukko.pro
export ANTHROPIC_AUTH_TOKEN=fetch_your_key
claude

Full setup is in the Claude Code guide.

Using with the OpenAI SDK

Python
bash
from openai import OpenAI

client = OpenAI(
    api_key="fetch_your_key",
    base_url="https://api.zukko.pro/v1"
)

response = client.responses.create(
    model="claude-sonnet-5",
    input="Write a haiku about programming"
)

print(response.output_text)

Error format

Errors follow the OpenAI format: error.message, error.type, error.code, and error.param. Handle them by code — Zukko's error text is in Russian.

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"
  }
}

Common errors: 401 — invalid API key; 402 insufficient_balance — balance below $0.01; 403 — email not verified or the model is not allowed for the key; 503 model_disabled — the model is switched off. Zukko has no request rate limiting of its own: its 429s are only key limits (key_daily_limit_reached, key_monthly_limit_reached); any other 429 comes from the model provider.

Previous
Key limits, idempotency and caching
Next
POST /v1/web-search
POST /v1/responses · Zukko Docs