Reference
Full OpenAPI SchemaPOST
/v1/responsesRequest Parameters
The Responses API allows you to generate text, execute tools, and handle multi-turn conversations. It supports both synchronous requests and streaming for real-time output.
Parameters may be supplied as either application/json or application/x-www-form-urlencoded.
Headers
| Header | Values | Required? |
|---|---|---|
Content-Type | application/json or application/x-www-form-urlencoded | Yes |
Authorization | Authorization token, usually in the form of Bearer [secret token] | Yes |
Body
Body Parameters
model
string
The model to use for this request, e.g. 'gpt-5.2'.
input
Context to provide to the model for the scope of this request. May either be a string or an array of input items. If a string is provided, it is interpreted as a user message.
previous_response_id
string
The ID of the response to use as the prior turn for this request.
include
Values
| reasoning.encrypted_content | includes encrypted reasoning content so that it may be rehydrated on a subsequent request. |
| message.output_text.logprobs | includes sampled logprobs in assistant messages. |
tools
array ofFunctionToolParam
A list of tools that the model may call while generating the response.
tool_choice
Controls which tool the model should use, if any.
metadata
Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard.
Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.
text
Configuration options for text output.
temperature
number
Sampling temperature to use, between 0 and 2. Higher values make the output more random.
top_p
number
Nucleus sampling parameter, between 0 and 1. The model considers only the tokens with the top cumulative probability.
presence_penalty
number
Penalizes new tokens based on whether they appear in the text so far.
frequency_penalty
number
Penalizes new tokens based on their frequency in the text so far.
parallel_tool_calls
boolean
Whether the model may call multiple tools in parallel.
stream
boolean
Whether to stream response events as server-sent events.
stream_options
Options that control streamed response behavior.
background
boolean
Whether to run the request in the background and return immediately.
max_output_tokens
integer
The maximum number of tokens the model may generate for this response.
max_tool_calls
integer
The maximum number of tool calls the model may make while generating the response.
reasoning
Configuration options for reasoning behavior.
safety_identifier
string
A stable identifier used for safety monitoring and abuse detection.
prompt_cache_key
string
A key to use when reading from or writing to the prompt cache.
truncation
Controls how the service truncates the input when it exceeds the model context window.
Values
| auto | Let the service decide how to truncate. |
| disabled | Disable service truncation. Context over the model's context limit will result in a 400 error. |
instructions
string
Additional instructions to guide the model for this request.
store
boolean
Whether to store the response so it can be retrieved later.
service_tier
The service tier to use for this request.
Values
| auto | Choose a service tier automatically based on current account state. |
| default | Choose the default service tier. |
| flex | Choose the flex service tier. |
| priority | Choose the priority service tier. |
top_logprobs
integer
The number of most likely tokens to return at each position, along with their log probabilities.
Response Parameters
Headers
| Header | Values | Required? |
|---|---|---|
Content-Type | application/json or text/event-stream | Yes |
Body
Response
id
string
required
The unique ID of the response that was created.
object
"response"
required
The object type, which was always `response`.
created_at
integer
required
The Unix timestamp (in seconds) for when the response was created.
completed_at
required
integer
The Unix timestamp (in seconds) for when the response was completed, if it was completed.
status
string
required
The status that was set for the response.
Details about why the response was incomplete, if applicable.
model
string
required
The model that generated this response.
previous_response_id
required
string
The ID of the previous response in the chain that was referenced, if any.
instructions
required
string
Additional instructions that were used to guide the model for this response.
The output items that were generated by the model.
The error that occurred, if the response failed.
The tools that were available to the model during response generation.
How the input was truncated by the service when it exceeded the model context window.
Values
| auto | Let the service decide how to truncate. |
| disabled | Disable service truncation. Context over the model's context limit will result in a 400 error. |
parallel_tool_calls
boolean
required
Whether the model was allowed to call multiple tools in parallel.
Configuration options for text output that were used.
top_p
number
required
The nucleus sampling parameter that was used for this response.
presence_penalty
number
required
The presence penalty that was used to penalize new tokens based on whether they appear in the text so far.
frequency_penalty
number
required
The frequency penalty that was used to penalize new tokens based on their frequency in the text so far.
top_logprobs
integer
required
The number of most likely tokens that were returned at each position, along with their log probabilities.
temperature
number
required
The sampling temperature that was used for this response.
Reasoning configuration and outputs that were produced for this response.
Token usage statistics that were recorded for the response, if available.
max_output_tokens
required
integer
The maximum number of tokens the model was allowed to generate for this response.
max_tool_calls
required
integer
The maximum number of tool calls the model was allowed to make while generating the response.
store
boolean
required
Whether this response was stored so it can be retrieved later.
background
boolean
required
Whether this request was run in the background.
service_tier
string
required
The service tier that was used for this response.
metadata
unknown
required
Developer-defined metadata that was associated with the response.
safety_identifier
required
string
A stable identifier that was used for safety monitoring and abuse detection.
prompt_cache_key
required
string
A key that was used to read from or write to the prompt cache.
API Objects
Enums
FunctionCallOutputStatusEnum
Similar to `FunctionCallStatus`. All three options are allowed here for compatibility, but because in practice these items will be provided by developers, only `completed` should be used.
Values
| in_progress | — |
| completed | — |
| incomplete | — |
FunctionCallStatus
Values
| in_progress | Model is currently sampling this item. |
| completed | Model has finished sampling this item. |
| incomplete | Model was interrupted from sampling this item partway through. This can occur, for example, if the model encounters a stop token or exhausts its output_token budget. |
ImageDetail
Values
| low | Restricts the model to a lower-resolution version of the image. |
| high | Allows the model to "see" a higher-resolution version of the image, usually increasing input token costs. |
| auto | Choose the detail level automatically. |
IncludeEnum
Values
| reasoning.encrypted_content | includes encrypted reasoning content so that it may be rehydrated on a subsequent request. |
| message.output_text.logprobs | includes sampled logprobs in assistant messages. |
MessageRole
Values
| user | End‑user input in the conversation. |
| assistant | Model-generated content in the conversation. |
| system | System-level instructions that set global behavior. |
| developer | Developer-supplied guidance that shapes the assistant’s behavior. |
MessageStatus
Values
| in_progress | Model is currently sampling this item. |
| completed | Model has finished sampling this item. |
| incomplete | Model was interrupted from sampling this item partway through. This can occur, for example, if the model encounters a stop token or exhausts its output_token budget. |
ReasoningEffortEnum
Values
| none | Restrict the model from performing any reasoning before emitting a final answer. |
| low | Use a lower reasoning effort for faster responses. |
| medium | Use a balanced reasoning effort. |
| high | Use a higher reasoning effort to improve answer quality. |
| xhigh | Use the maximum reasoning effort available. |
ReasoningSummaryEnum
Values
| concise | Emit concise summaries of reasoning content. |
| detailed | Emit details summaries of reasoning content. |
| auto | Allow the model to decide when to summarize. |
ServiceTierEnum
Values
| auto | Choose a service tier automatically based on current account state. |
| default | Choose the default service tier. |
| flex | Choose the flex service tier. |
| priority | Choose the priority service tier. |
ToolChoiceValueEnum
Values
| none | Restrict the model from calling any tools. |
| auto | Let the model choose the tools from among the provided set. |
| required | Require the model to call a tool. |
TruncationEnum
Values
| auto | Let the service decide how to truncate. |
| disabled | Disable service truncation. Context over the model's context limit will result in a 400 error. |
VerbosityEnum
Values
| low | Instruct the model to emit less verbose final responses. |
| medium | Use the model's default verbosity setting. |
| high | Instruct the model to emit more verbose final responses. |
Unions
Annotation
An annotation that applies to a span of output text.
ItemField
An item representing a message, tool call, tool output, reasoning, or other response element.
ItemParam
An internal identifier for an item to reference.
ResponsesToolParam
SpecificToolChoiceParam
TextFormatParam
Tool
A tool that can be used to generate a response.
ToolChoiceParam
Controls which tool the model should use, if any.
Objects
AllowedToolChoice
type
"allowed_tools"
required
toolsFunctionToolChoice[]
required
modeenum
required
Values
| none | Restrict the model from calling any tools. |
| auto | Let the model choose the tools from among the provided set. |
| required | Require the model to call a tool. |
AllowedToolsParam
type
"allowed_tools"
required
The tool choice type. Always `allowed_tools`.
toolsSpecificToolChoiceParam[]
required
The list of tools that are permitted for this request.
modeenum
How to select a tool from the allowed set.
Values
| none | Restrict the model from calling any tools. |
| auto | Let the model choose the tools from among the provided set. |
| required | Require the model to call a tool. |
AssistantMessageItemParam
id
string
The unique ID of this message item.
type
"message"
required
The item type. Always `message`.
role
"assistant"
required
The role of the message author. Always `assistant`.
The message content, as an array of content parts.
status
string
The status of the message item.
DeveloperMessageItemParam
id
string
The unique ID of this message item.
type
"message"
required
The item type. Always `message`.
role
"developer"
required
The message role. Always `developer`.
The message content, as an array of content parts.
status
string
The status of the message item.
EmptyModelParam
Error
An error that occurred while generating the response.
codestring
required
A machine-readable error code that was returned.
messagestring
required
A human-readable description of the error that was returned.
FunctionCall
A function tool call that was generated by the model.
type
"function_call"
required
The type of the item. Always `function_call`.
idstring
required
The unique ID of the function call item.
call_idstring
required
The unique ID of the function tool call that was generated.
namestring
required
The name of the function that was called.
argumentsstring
required
The arguments JSON string that was generated.
statusenum
required
The status of the function call item that was recorded.
Values
| in_progress | Model is currently sampling this item. |
| completed | Model has finished sampling this item. |
| incomplete | Model was interrupted from sampling this item partway through. This can occur, for example, if the model encounters a stop token or exhausts its output_token budget. |
created_bystring
The identifier of the actor that created the item.
FunctionCallItemParam
id
string
The unique ID of this function tool call.
call_idstring
required
The unique ID of the function tool call generated by the model.
type
"function_call"
required
The item type. Always `function_call`.
namestring
required
The name of the function to call.
argumentsstring
required
The function arguments as a JSON string.
status
The status of the function tool call.
Values
| in_progress | Model is currently sampling this item. |
| completed | Model has finished sampling this item. |
| incomplete | Model was interrupted from sampling this item partway through. This can occur, for example, if the model encounters a stop token or exhausts its output_token budget. |
FunctionCallOutput
A function tool call output that was returned by the tool.
type
"function_call_output"
required
The type of the function tool call output. Always `function_call_output`.
idstring
required
The unique ID of the function tool call output. Populated when this item is returned via API.
call_idstring
required
The unique ID of the function tool call generated by the model.
A JSON string of the output of the function tool call.
statusenum
required
The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API.
Values
| in_progress | — |
| completed | — |
| incomplete | — |
created_bystring
The identifier of the actor that created the item.
FunctionCallOutputItemParam
The output of a function tool call.
id
string
The unique ID of the function tool call output. Populated when this item is returned via API.
call_idstring
required
The unique ID of the function tool call generated by the model.
type
"function_call_output"
required
The type of the function tool call output. Always `function_call_output`.
output
string
required
Text, image, or file output of the function tool call.
status
The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API.
Values
| in_progress | Model is currently sampling this item. |
| completed | Model has finished sampling this item. |
| incomplete | Model was interrupted from sampling this item partway through. This can occur, for example, if the model encounters a stop token or exhausts its output_token budget. |
FunctionTool
Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling).
type
"function"
required
The type of the function tool. Always `function`.
namestring
required
The name of the function to call.
description
string
required
A description of the function. Used by the model to determine whether or not to call the function.
parameters
object
required
A JSON schema object describing the parameters of the function.
strict
boolean
required
Whether to enforce strict parameter validation. Default `true`.
FunctionToolChoice
type
"function"
required
namestring
FunctionToolParam
IncompleteDetails
Details about why the response was incomplete.
reasonstring
required
The reason the response could not be completed.
InputFileContent
A file input to the model.
type
"input_file"
required
The type of the input item. Always `input_file`.
filenamestring
The name of the file to be sent to the model.
file_urlstring
The URL of the file to be sent to the model.
InputFileContentParam
A file input to the model.
type
"input_file"
required
The type of the input item. Always `input_file`.
filename
string
The name of the file to be sent to the model.
file_data
string
The base64-encoded data of the file to be sent to the model.
file_url
string
The URL of the file to be sent to the model.
InputImageContent
An image input to the model. Learn about [image inputs](/docs/guides/vision).
type
"input_image"
required
The type of the input item. Always `input_image`.
image_url
string
required
The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL.
detailenum
required
The detail level of the image to be sent to the model. One of `high`, `low`, or `auto`. Defaults to `auto`.
Values
| low | Restricts the model to a lower-resolution version of the image. |
| high | Allows the model to "see" a higher-resolution version of the image, usually increasing input token costs. |
| auto | Choose the detail level automatically. |
InputImageContentParamAutoParam
An image input to the model. Learn about [image inputs](/docs/guides/vision)
type
"input_image"
required
The type of the input item. Always `input_image`.
image_url
string
The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL.
detail
The detail level of the image to be sent to the model. One of `high`, `low`, or `auto`. Defaults to `auto`.
Values
| low | Restricts the model to a lower-resolution version of the image. |
| high | Allows the model to "see" a higher-resolution version of the image, usually increasing input token costs. |
| auto | Choose the detail level automatically. |
InputTextContent
A text input to the model.
type
"input_text"
required
The type of the input item. Always `input_text`.
textstring
required
The text input to the model.
InputTextContentParam
A text input to the model.
type
"input_text"
required
The type of the input item. Always `input_text`.
textstring
required
The text input to the model.
InputTokensDetails
A breakdown of input token usage that was recorded.
cached_tokensinteger
required
The number of input tokens that were served from cache.
InputVideoContent
A content block representing a video input to the model.
type
"input_video"
required
The type of the input content. Always `input_video`.
video_urlstring
required
A base64 or remote url that resolves to a video file.
ItemReferenceParam
An internal identifier for an item to reference.
type
"item_reference"
The type of item to reference. Always `item_reference`.
idstring
required
The ID of the item to reference.
JsonObjectResponseFormat
type
"json_object"
required
JsonSchemaResponseFormat
type
"json_schema"
required
namestring
required
description
string
required
schemaunknown
required
strictboolean
required
JsonSchemaResponseFormatParam
type
"json_schema"
The type of response format being defined. Always `json_schema`.
descriptionstring
A description of what the response format is for, used by the model to
determine how to respond in the format.
namestring
The name of the response format. Must be a-z, A-Z, 0-9, or contain
underscores and dashes, with a maximum length of 64.
schemaobject
The schema for the response format, described as a JSON Schema object.
strict
boolean
Whether to enable strict schema adherence when generating the output.
If set to true, the model will always follow the exact schema defined
in the `schema` field. Only a subset of JSON Schema is supported when
`strict` is `true`.
LogProb
The log probability of a token.
tokenstring
required
logprobnumber
required
bytesinteger[]
required
top_logprobsTopLogProb[]
required
Message
A message to or from the model.
type
"message"
required
The type of the message. Always set to `message`.
idstring
required
The unique ID of the message.
statusenum
required
The status of item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API.
Values
| in_progress | Model is currently sampling this item. |
| completed | Model has finished sampling this item. |
| incomplete | Model was interrupted from sampling this item partway through. This can occur, for example, if the model encounters a stop token or exhausts its output_token budget. |
roleenum
required
The role of the message. One of `unknown`, `user`, `assistant`, `system`, `critic`, `discriminator`, `developer`, or `tool`.
Values
| user | End‑user input in the conversation. |
| assistant | Model-generated content in the conversation. |
| system | System-level instructions that set global behavior. |
| developer | Developer-supplied guidance that shapes the assistant’s behavior. |
contentInputTextContent[]
required
The content of the message
MetadataParam
Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard.
Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.
OutputTextContent
A text output from the model.
type
"output_text"
required
The type of the output text. Always `output_text`.
textstring
required
The text output from the model.
annotationsAnnotation[]
required
The annotations of the text output.
logprobsLogProb[]
required
OutputTextContentParam
type
"output_text"
required
The content type. Always `output_text`.
textstring
required
The text content.
annotations
Citations associated with the text content.
OutputTokensDetails
A breakdown of output token usage that was recorded.
reasoning_tokensinteger
required
The number of output tokens that were attributed to reasoning.
Reasoning
Reasoning configuration and metadata that were used for the response.
The reasoning effort that was requested for the model, if specified.
Values
| none | Restrict the model from performing any reasoning before emitting a final answer. |
| low | Use a lower reasoning effort for faster responses. |
| medium | Use a balanced reasoning effort. |
| high | Use a higher reasoning effort to improve answer quality. |
| xhigh | Use the maximum reasoning effort available. |
A model-generated summary of its reasoning that was produced, if available.
Values
| concise | Emit concise summaries of reasoning content. |
| detailed | Emit details summaries of reasoning content. |
| auto | Allow the model to decide when to summarize. |
ReasoningItemParam
id
string
The unique ID of this reasoning item.
type
"reasoning"
required
The item type. Always `reasoning`.
summaryReasoningSummaryContentParam[]
required
Reasoning summary content associated with this item.
encrypted_content
string
An encrypted representation of the reasoning content.
ReasoningParam
**gpt-5 and o-series models only** Configuration options for [reasoning models](https://platform.openai.com/docs/guides/reasoning).
effort
Controls the level of reasoning effort the model should apply. Higher effort may increase latency and cost.
Values
| none | Restrict the model from performing any reasoning before emitting a final answer. |
| low | Use a lower reasoning effort for faster responses. |
| medium | Use a balanced reasoning effort. |
| high | Use a higher reasoning effort to improve answer quality. |
| xhigh | Use the maximum reasoning effort available. |
summary
Controls whether the response includes a reasoning summary.
Values
| concise | Emit concise summaries of reasoning content. |
| detailed | Emit details summaries of reasoning content. |
| auto | Allow the model to decide when to summarize. |
ReasoningSummaryContentParam
type
"summary_text"
required
The content type. Always `summary_text`.
textstring
required
The reasoning summary text.
ReasoningTextContent
Reasoning text from the model.
type
"reasoning_text"
required
The type of the reasoning text. Always `reasoning_text`.
textstring
required
The reasoning text from the model.
RefusalContent
A refusal from the model.
type
"refusal"
required
The type of the refusal. Always `refusal`.
refusalstring
required
The refusal explanation from the model.
RefusalContentParam
type
"refusal"
required
The content type. Always `refusal`.
refusalstring
required
The refusal text.
SpecificFunctionParam
type
"function"
required
The tool to call. Always `function`.
namestring
required
The name of the function tool to call.
StreamOptionsParam
Options that control streamed response behavior.
include_obfuscationboolean
Whether to obfuscate sensitive information in streamed output. Defaults to `true`.
SummaryTextContent
A summary text from the model.
type
"summary_text"
required
The type of the object. Always `summary_text`.
textstring
required
A summary of the reasoning output from the model so far.
SystemMessageItemParam
id
string
The unique ID of this message item.
type
"message"
required
The item type. Always `message`.
role
"system"
required
The message role. Always `system`.
The message content, as an array of content parts.
status
string
The status of the message item.
TextContent
A text content.
type
"text"
required
textstring
required
TextField
verbosityenum
Values
| low | Instruct the model to emit less verbose final responses. |
| medium | Use the model's default verbosity setting. |
| high | Instruct the model to emit more verbose final responses. |
TextParam
The format configuration for text output.
verbosityenum
Controls the level of detail in generated text output.
Values
| low | Instruct the model to emit less verbose final responses. |
| medium | Use the model's default verbosity setting. |
| high | Instruct the model to emit more verbose final responses. |
TextResponseFormat
type
"text"
required
TopLogProb
The top log probability of a token.
tokenstring
required
logprobnumber
required
bytesinteger[]
required
UrlCitationBody
A citation for a web resource used to generate a model response.
type
"url_citation"
required
The type of the URL citation. Always `url_citation`.
urlstring
required
The URL of the web resource.
start_indexinteger
required
The index of the first character of the URL citation in the message.
end_indexinteger
required
The index of the last character of the URL citation in the message.
titlestring
required
The title of the web resource.
UrlCitationParam
type
"url_citation"
required
The citation type. Always `url_citation`.
start_indexinteger
required
The index of the first character of the citation in the message.
end_indexinteger
required
The index of the last character of the citation in the message.
urlstring
required
The URL of the cited resource.
titlestring
required
The title of the cited resource.
Usage
Token usage statistics that were recorded for the response.
input_tokensinteger
required
The number of input tokens that were used to generate the response.
output_tokensinteger
required
The number of output tokens that were generated by the model.
total_tokensinteger
required
The total number of tokens that were used.
input_tokens_detailsInputTokensDetails
required
A breakdown of input token usage that was recorded.
output_tokens_detailsOutputTokensDetails
required
A breakdown of output token usage that was recorded.
UserMessageItemParam
id
string
The unique ID of this message item.
type
"message"
required
The item type. Always `message`.
role
"user"
required
The message role. Always `user`.
content
required
The message content, as an array of content parts.
status
string
The status of the message item.