Skip to content

OpenAI Responses API reference for GPT and Claude

The OpenAI Responses reference for GPT and Claude models, with what each parameter does here, tools, structured output, reasoning, streaming and errors.

Updated October 2, 2026
On this page

The newer OpenAI format: one request with input, and a reply made of items such as text and function calls. It works with GPT and Claude models. Gemini models are not served on this endpoint; use Chat Completions, Messages or generateContent for them.

POSThttps://api.5abeer.ai/v1/responses

Authentication#

Send your key in the Authorization header as Bearer followed by the key, with the OpenAI-compatible base URL. The official OpenAI libraries call this endpoint with client.responses.create; see Base URLs.

Quick example#

curl --request POST "https://api.5abeer.ai/v1/responses" \
  --header "Authorization: Bearer $KHABEER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"model":"claude-sonnet-5.5","input":"Write a product idea in one sentence."}'
Response
{
  "id": "resp_68c1",
  "object": "response",
  "model": "claude-sonnet-5.5",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Hello! How can I help you today?"
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 21,
    "output_tokens": 12,
    "total_tokens": 33
  }
}

The key is read from KHABEER_API_KEY, so it never appears in your code.

Parameters#

Each row shows what happens to the parameter for each model family: supported means we pass it to the model; ignored means the request is accepted but the parameter has no effect, so don't rely on it; rejected means the request fails. We measured these against the gateway itself.

ParameterDescriptionClaudeGPTGemini
modelstringrequiredThe model id, as in the models list.ClaudeSupportedGPTSupportedGeminiRejected
inputstring | arrayrequiredOne string, or a list of messages and parts, images and function results included.ClaudeSupportedGPTSupportedGeminiRejected
instructionsstringSystem instructions for the model.ClaudeSupportedGPTSupportedGeminiRejected
max_output_tokensintegerThe maximum number of output tokens.ClaudeSupportedGPTIgnoredGeminiRejected
temperaturenumberHow random the reply is.ClaudeSupportedGPTIgnoredGeminiRejected
top_pnumberSample only from the most likely tokens.ClaudeSupportedGPTIgnoredGeminiRejected
streambooleanSend the reply as a series of events. See Streaming.ClaudeSupportedGPTSupportedGeminiRejected
toolsarrayFunctions the model can call.ClaudeSupportedGPTSupportedGeminiRejected
tool_choicestring | objectauto, none, required or one named function.ClaudeSupportedGPTSupportedGeminiRejected
parallel_tool_callsbooleanAllow or prevent several calls in one reply.ClaudeIgnoredGPTSupportedGeminiRejected
textobjectformat for structured output with a json_schema. For Claude models use a tool with a schema.ClaudeIgnoredGPTSupportedGeminiRejected
reasoningobjecteffort sets how hard the model thinks: low, medium or high.ClaudeSupportedGPTSupportedGeminiRejected
includearrayExtra fields in the reply, such as reasoning.encrypted_content.ClaudeIgnoredGPTSupportedGeminiRejected
prompt_cache_keystringA stable key that groups similar requests for caching.ClaudeIgnoredGPTSupportedGeminiRejected
previous_response_idstringHas no effect here. Send the whole conversation in input each time.ClaudeIgnoredGPTIgnoredGeminiRejected
storebooleanHas no effect here.ClaudeIgnoredGPTIgnoredGeminiRejected
truncationstringTrim a long conversation automatically.ClaudeIgnoredGPTIgnoredGeminiRejected
metadataobjectYour own values attached to the request.ClaudeIgnoredGPTIgnoredGeminiRejected
userstringAn id for the end user in your system.ClaudeIgnoredGPTIgnoredGeminiRejected

Conversations#

Each request stands alone: previous_response_id and store have no effect here. To continue a conversation, send all of it in input every time, your messages with the role user and the model's replies with the role assistant, as in the full conversation example.

Images in the request#

Add an input_image part to a user message, with image_url set to a data: URL in Base64 or a public https URL, next to an input_text part.

Streaming#

With "stream": true the reply arrives as named events: response.created, then response.output_text.delta with the text in parts, and response.completed with the full reply and usage. If the request fails mid-way you get response.failed with the error code. Details in Streaming.

Examples#

Streaming#

curl -N https://api.5abeer.ai/v1/responses \
  -H "Authorization: Bearer $KHABEER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-sol",
    "input": "Write a product idea in one sentence.",
    "stream": true
  }'
Stream events
event: response.created
data: {"type":"response.created","response":{"id":"resp_p8a01","object":"response","status":"in_progress","model":"gpt-5.6-sol"}}

event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_p8a01","output_index":0,"content_index":0,"delta":"Lumen Notes: "}

event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_p8a01","output_index":0,"content_index":0,"delta":"a notebook that turns voice memos "}

event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_p8a01","output_index":0,"content_index":0,"delta":"into tidy to-do lists."}

event: response.completed
data: {"type":"response.completed","response":{"id":"resp_p8a01","object":"response","created_at":1790000000,"status":"completed","model":"gpt-5.6-sol","output":[{"type":"message","id":"msg_p8a01","role":"assistant","status":"completed","content":[{"type":"output_text","text":"Lumen Notes: a notebook that turns voice memos into tidy to-do lists.","annotations":[]}]}],"usage":{"input_tokens":21,"output_tokens":18,"total_tokens":39}}}

A full conversation with instructions#

curl https://api.5abeer.ai/v1/responses \
  -H "Authorization: Bearer $KHABEER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-5",
    "instructions": "Answer in one sentence.",
    "input": [
      {
        "role": "user",
        "content": [
          {
            "type": "input_text",
            "text": "Suggest a product name."
          }
        ]
      },
      {
        "role": "assistant",
        "content": [
          {
            "type": "output_text",
            "text": "Lumen Notes."
          }
        ]
      },
      {
        "role": "user",
        "content": [
          {
            "type": "input_text",
            "text": "Now a slogan for it."
          }
        ]
      }
    ],
    "max_output_tokens": 300,
    "temperature": 0.4,
    "top_p": 0.9,
    "reasoning": {
      "effort": "low"
    }
  }'
Response shape
{
  "id": "resp_p8a01",
  "object": "response",
  "created_at": 1790000000,
  "status": "completed",
  "model": "claude-opus-5",
  "output": [
    {
      "type": "message",
      "id": "msg_p8a01",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "Lumen Notes: a notebook that turns voice memos into tidy to-do lists.",
          "annotations": []
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 21,
    "output_tokens": 18,
    "total_tokens": 39
  }
}

Calling a function#

curl https://api.5abeer.ai/v1/responses \
  -H "Authorization: Bearer $KHABEER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-sol",
    "input": "What is the weather in Cairo?",
    "tools": [
      {
        "type": "function",
        "name": "get_weather",
        "description": "Get the weather for a city",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string"
            }
          },
          "required": [
            "city"
          ]
        }
      }
    ],
    "tool_choice": "auto",
    "parallel_tool_calls": false
  }'
Response shape
{
  "id": "resp_p8a01",
  "object": "response",
  "created_at": 1790000000,
  "status": "completed",
  "model": "gpt-5.6-sol",
  "output": [
    {
      "type": "function_call",
      "id": "fc_p8a01",
      "call_id": "call_p8a01",
      "name": "get_weather",
      "arguments": "{\"city\":\"Cairo\"}",
      "status": "completed"
    }
  ],
  "usage": {
    "input_tokens": 21,
    "output_tokens": 18,
    "total_tokens": 39
  }
}

JSON output with a schema#

curl https://api.5abeer.ai/v1/responses \
  -H "Authorization: Bearer $KHABEER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-sol",
    "input": "Give me one product idea.",
    "text": {
      "format": {
        "type": "json_schema",
        "name": "idea",
        "strict": true,
        "schema": {
          "type": "object",
          "properties": {
            "idea": {
              "type": "string"
            }
          },
          "required": [
            "idea"
          ],
          "additionalProperties": false
        }
      }
    },
    "reasoning": {
      "effort": "low"
    },
    "include": [
      "reasoning.encrypted_content"
    ],
    "prompt_cache_key": "product-ideas-v1"
  }'
Response shape
{
  "id": "resp_p8a01",
  "object": "response",
  "created_at": 1790000000,
  "status": "completed",
  "model": "gpt-5.6-sol",
  "output": [
    {
      "type": "message",
      "id": "msg_p8a01",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "{\"idea\":\"Lumen Notes: a notebook that turns voice memos into tidy to-do lists.\"}",
          "annotations": []
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 21,
    "output_tokens": 18,
    "total_tokens": 39
  }
}

Fields accepted without effect#

curl https://api.5abeer.ai/v1/responses \
  -H "Authorization: Bearer $KHABEER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-sol",
    "input": "Write a product idea in one sentence.",
    "store": false,
    "previous_response_id": "resp_123",
    "truncation": "auto",
    "metadata": {
      "order": "42"
    },
    "user": "user-123"
  }'
Response shape
{
  "id": "resp_p8a01",
  "object": "response",
  "created_at": 1790000000,
  "status": "completed",
  "model": "gpt-5.6-sol",
  "output": [
    {
      "type": "message",
      "id": "msg_p8a01",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "Lumen Notes: a notebook that turns voice memos into tidy to-do lists.",
          "annotations": []
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 21,
    "output_tokens": 18,
    "total_tokens": 39
  }
}

The request above was run on the local test stack on 2026-10-02; the reply shows the shape, and its text is an example.

Errors#

The common codes are the same as for Chat Completions, with one difference: when a pay-as-you-go key reaches the spend limit you set, this endpoint answers 429 with the code insufficient_quota, the way OpenAI does, instead of API_KEY_QUOTA_EXHAUSTED. Raise the key's limit in its settings. The other shapes and codes are in Limits and error codes.

Models for this format#

per 1M tokens

Official price from the provider's page, checked October 19, 2026.

All models and prices

Claude models work here too; see the models list.