OpenAI Responses

Create text, image, tool-call, and reasoning responses with the OpenAI-compatible Responses API.

The Responses API represents text, images, files, tool calls, and reasoning output as typed items. It is designed for applications that need multimodal input, built-in tools, stateful interactions, or semantic streaming events. Available item types, tools, and advanced fields depend on the selected model.

POST/v1/responses

Create model responses from text, images, files, or Typed Input Items. The API can return Output Items such as messages, reasoning items, and tool calls, and can stream semantic events through SSE.

Support for images, built-in tools, reasoning, stateful interactions, and structured output depends on the selected model and provider channel. Start with a minimal text request, then enable advanced fields one at a time.

Authorization

bearerAuth

AuthorizationBearer <token>

Use Bearer your-api-key in the Authorization Header.

In: header

Request Body

Responses represents input, tools, and output with Typed Items. Choose a view for your task; field support depends on the model and provider channel.

application/json

Text input

Pass a string directly to input for the shortest path, or use message-style Typed Items.

model: A Responses-capable model ID visible to the current API key.
input: A string or an array of Typed Input Items.
instructions: High-level instructions that apply only to this response.

application/json

{
  "model": "MODEL_ID",
  "input": "Introduce yourself in three sentences."
}

Basic text response. input can be a string or Typed Input Items.

background?boolean|null

Whether responses run in the background. The availability of background mode depends on the model, channel, and account permissions.

Defaultfalse

context_management?array<>|null

Context management configuration for the current request, such as compression when a specified token threshold is reached.

conversation?string||null

The Conversation to which this response belongs. Conversation IDs or objects containing id can be passed; They cannot be used together with previous_response_id.

model?string

The Responses text model ID to use. Select a model visible to the current API key.

Length1 <= length

input?text input|array<||||||||||||||||||||||||||||||>

Text input. Pass a string directly, or provide messages and other Typed Items.

include?array<>|null

Specify the extended data that needs to be appended to the response.

instructions?string|array<||||||||||||||||||||||||||||||>|null

System or developer messages used in this response to high-level instructions. When using previous_response_id, instructions from the previous response are not automatically inherited.

max_output_tokens?integer|null

The maximum number of tokens a response can generate, including visible output and inference tokens.

max_tool_calls?integer|null

This response can handle the maximum number of built-in tool calls it can handle, rather than the individual cap for each tool.

Range0 <= value

metadata?|null

Key-value information attached to the response object. The key length is 64 characters, and the value is up to 512 characters.

Propertiesproperties <= 16

parallel_tool_calls?boolean|null

Whether the model is allowed to run tool calls in parallel.

Defaulttrue

moderation?|null

Moderation configuration for response input and output.

previous_response_id?string|null

The unique ID of the previous response, used to continue stateful interactions. It cannot be used together with conversation; The instructions of the previous response are not automatically inherited.

prompt?|null

Prompt templates and their variable references have been saved.

prompt_cache_key?string|null

Used to improve the hit rate of caching prompts for similar requests and to replace the user's caching function.

prompt_cache_options?|null

Request-level prompts for cache configuration. Content blocks can be used with prompt_cache_breakpoint flags to explicit cache boundaries.

prompt_cache_retention?string|null

Deprecated

Deprecated; please use prompt_cache_options.ttl. This field is reserved for compatibility with the old cache reservation policy.

Value in

"in_memory"
"24h"
null

reasoning?|null

Reasoning configuration. Applies only to models that support reasoning.

service_tier?string|null

The service level used by the request. The request value may differ from the actual return value of the response; for example, a fast request may return priority.

Default"auto"

Value in

"auto"
"default"
"flex"
"scale"
"priority"
"fast"
"ultrafast"
null

safety_identifier?string|null

Stable end-user identification for security and abuse monitoring. It is recommended to perform hashing first to avoid transmitting personally identifiable information.

Lengthlength <= 64

store?boolean|null

Whether to store the generated response. Storage, retrieval, and retention behavior depends on platform support.

Defaulttrue

stream?boolean|null

When true, returns Responses semantic events through Server-Sent Events.

Defaultfalse

stream_options?|null

Stream response configuration. Only used when the stream is true.

temperature?number|null

Sampling temperature. Usually, only one of the temperature or top_p is adjusted.

Range0 <= value <= 2

Default1

text?

tool_choice?||||||||

Control whether and how the model chooses tools.

tools?array<|||||||||||||>

Built-in tools or custom functions that models can use. The actual support depends on the model and channel.

top_logprobs?integer|null

Number of most likely candidate tokens to return at each output token position, from 0 to 20.

Range0 <= value <= 20

top_p?number|null

Nucleus sampling probability mass. Usually, adjust either top_p or temperature, but not both.

Range0 <= value <= 1

Default1

truncation?string|null

Deprecated

Truncation policy when the context exceeds the window. disabled will cause the overlimit request to fail.

Default"disabled"

Value in

"auto"
"disabled"
null

user?string

Deprecated

Deprecated. Use safety_identifier for security identifiers, and use prompt_cache_key for cache groups.

Tool, state, reasoning, and multimodal support in Responses can vary by model and provider channel. Start with a minimal text request, then enable advanced fields one at a time.

Response Body

`application/json`

curl -X POST "https://example.com/v1/responses" \  -H "Content-Type: application/json" \  -d '{    "model": "MODEL_ID",    "input": "Please tell a bedtime story about a unicorn in three sentences."  }'

{
  "id": "resp_example",
  "object": "response",
  "created_at": 1741476542,
  "status": "completed",
  "error": null,
  "incomplete_details": null,
  "instructions": null,
  "max_output_tokens": null,
  "model": "MODEL_ID",
  "output": [
    {
      "id": "msg_example",
      "type": "message",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Under the moonlight, a unicorn discovers a secret path to the starry sky.",
          "annotations": []
        }
      ]
    }
  ],
  "parallel_tool_calls": true,
  "previous_response_id": null,
  "reasoning": {
    "effort": null,
    "summary": null
  },
  "store": true,
  "temperature": 1,
  "text": {
    "format": {
      "type": "text"
    }
  },
  "tool_choice": "auto",
  "tools": [],
  "top_p": 1,
  "truncation": "disabled",
  "usage": {
    "input_tokens": 18,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 22,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 40
  },
  "user": null,
  "metadata": {}
}

OpenAI Responses documentationReview the upstream protocol and recent field changes.

Authorization

Request Body

Response Body

200application/json

400application/json

401application/json

403application/json

404application/json

429application/json

500application/json

502application/json

503application/json

504application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`