Create a response
POST
/v1/responses Generate text, execute tools, and handle multi-turn conversations.
Headers 2 required headers
Content-Type-
application/jsonorapplication/x-www-form-urlencoded Authorization-
Authorization token, usually
Bearer [secret token].
Body parameters
Supply parameters as application/json or application/x-www-form-urlencoded.
The model to use for this request, e.g. 'gpt-5.2'.
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.
{
"model": "your-model",
"input": "Say hello"
}The ID of the response to use as the prior turn for this request.
Allowed 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.
A list of tools that the model may call while generating the response.
Accepted types
Controls which tool the model should use, if any.
Accepted types
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.
Accepted types
Configuration options for text output.
Accepted types
Sampling temperature to use, between 0 and 2. Higher values make the output more
random.
Nucleus sampling parameter, between 0 and 1. The model considers only the tokens
with the top cumulative probability.
Penalizes new tokens based on whether they appear in the text so far.
Penalizes new tokens based on their frequency in the text so far.
Whether the model may call multiple tools in parallel.
Whether to stream response events as server-sent events.
Options that control streamed response behavior.
Accepted types
Whether to run the request in the background and return immediately.
The maximum number of tokens the model may generate for this response.
The maximum number of tool calls the model may make while generating the response.
Configuration options for reasoning behavior.
Accepted types
A stable identifier used for safety monitoring and abuse detection.
A key to use when reading from or writing to the prompt cache.
Controls how the service truncates the input when it exceeds the model context
window.
Allowed 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.
Additional instructions to guide the model for this request.
Whether to store the response so it can be retrieved later.
The service tier to use for this request.
Allowed 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.
The number of most likely tokens to return at each position, along with their log
probabilities.
Headers 1 required header
Content-Type-
application/jsonortext/event-stream
Response body
The unique ID of the response that was created.
The object type, which was always
response.The Unix timestamp (in seconds) for when the response was created.
The Unix timestamp (in seconds) for when the response was completed, if it was
completed.
The status that was set for the response.
Details about why the response was incomplete, if applicable.
Accepted types
The model that generated this response.
The ID of the previous response in the chain that was referenced, if any.
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.
Accepted types
The tools that were available to the model during response generation.
Accepted types
How the input was truncated by the service when it exceeded the model context
window.
Allowed 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.
Whether the model was allowed to call multiple tools in parallel.
Configuration options for text output that were used.
The nucleus sampling parameter that was used for this response.
The presence penalty that was used to penalize new tokens based on whether they
appear in the text so far.
The frequency penalty that was used to penalize new tokens based on their frequency
in the text so far.
The number of most likely tokens that were returned at each position, along with
their log probabilities.
The sampling temperature that was used for this response.
Reasoning configuration and outputs that were produced for this response.
Accepted types
Token usage statistics that were recorded for the response, if available.
Accepted types
The maximum number of tokens the model was allowed to generate for this response.
The maximum number of tool calls the model was allowed to make while generating the
response.
Whether this response was stored so it can be retrieved later.
Whether this request was run in the background.
The service tier that was used for this response.
Developer-defined metadata that was associated with the response.
A stable identifier that was used for safety monitoring and abuse detection.
A key that was used to read from or write to the prompt cache.
Streaming events
Set stream to true to receive server-sent
events as the response is generated.
response.created
A streaming event that indicated the response was created.
The type of the event, always
response.created.The sequence number of the event that was emitted.
The response snapshot that was emitted with the event.
response.queued
A streaming event that indicated the response was queued.
The type of the event, always
response.queued.The sequence number of the event that was emitted.
The response snapshot that was emitted with the event.
response.in_progress
A streaming event that indicated the response was in progress.
The type of the event, always
response.in_progress.The sequence number of the event that was emitted.
The response snapshot that was emitted with the event.
response.completed
A streaming event that indicated the response was completed.
The type of the event, always
response.completed.The sequence number of the event that was emitted.
The response snapshot that was emitted with the event.
response.failed
A streaming event that indicated the response had failed.
The type of the event, always
response.failed.The sequence number of the event that was emitted.
The response snapshot that was emitted with the event.
response.incomplete
A streaming event that indicated the response was incomplete.
The type of the event, always
response.incomplete.The sequence number of the event that was emitted.
The response snapshot that was emitted with the event.
response.output_item.added
A streaming event that indicated an output item was added to the response.
The type of the event, always
response.output_item.added.The sequence number of the event that was emitted.
The index of the output item that was added.
An item representing a message, tool call, tool output, reasoning, or other
response element.
Accepted types
response.output_item.done
A streaming event that indicated an output item was completed.
The type of the event, always
response.output_item.done.The sequence number of the event that was emitted.
The index of the output item that was completed.
An item representing a message, tool call, tool output, reasoning, or other
response element.
Accepted types
response.reasoning_summary_part.added
A streaming event that indicated a reasoning summary part was added.
The type of the event, always
response.reasoning_summary_part.added.The sequence number of the event that was emitted.
The ID of the item that was updated.
The index of the output item that was updated.
The index of the summary part that was added.
A content part that makes up an input or output item.
response.reasoning_summary_part.done
A streaming event that indicated a reasoning summary part was completed.
The type of the event, always
response.reasoning_summary_part.done.The sequence number of the event that was emitted.
The ID of the item that was updated.
The index of the output item that was updated.
The index of the summary part that was completed.
A content part that makes up an input or output item.
response.content_part.added
A streaming event that indicated a content part was added.
The type of the event, always
response.content_part.added.The sequence number of the event that was emitted.
The ID of the item that was updated.
The index of the output item that was updated.
The index of the content part that was added.
A content part that makes up an input or output item.
response.content_part.done
A streaming event that indicated a content part was completed.
The type of the event, always
response.content_part.done.The sequence number of the event that was emitted.
The ID of the item that was updated.
The index of the output item that was updated.
The index of the content part that was completed.
A content part that makes up an input or output item.
response.output_text.delta
A streaming event that indicated output text was incrementally added.
The type of the event, always
response.output_text.delta.The sequence number of the event that was emitted.
The ID of the item that was updated.
The index of the output item that was updated.
The index of the content part that was updated.
The text delta that was appended.
The token log probabilities that were emitted with the delta, if any.
An obfuscation string that was added to pad the event payload.
response.output_text.done
A streaming event that indicated output text was completed.
The type of the event, always
response.output_text.done.The sequence number of the event that was emitted.
The ID of the item that was updated.
The index of the output item that was updated.
The index of the content part that was completed.
The final text that was emitted.
The token log probabilities that were emitted with the final text, if any.
response.refusal.delta
A streaming event that indicated refusal text was incrementally added.
The type of the event, always
response.refusal.delta.The sequence number of the event that was emitted.
The ID of the item that was updated.
The index of the output item that was updated.
The index of the refusal content that was updated.
The refusal text delta that was appended.
response.refusal.done
A streaming event that indicated refusal text was completed.
The type of the event, always
response.refusal.done.The sequence number of the event that was emitted.
The ID of the item that was updated.
The index of the output item that was updated.
The index of the refusal content that was completed.
The final refusal text that was emitted.
response.reasoning.delta
A streaming event that indicated reasoning text was incrementally added.
The type of the event, always
response.reasoning.delta.The sequence number of the event that was emitted.
The ID of the item that was updated.
The index of the output item that was updated.
The index of the reasoning content that was updated.
The reasoning text delta that was appended.
An obfuscation string that was added to pad the event payload.
response.reasoning.done
A streaming event that indicated reasoning text was completed.
The type of the event, always
response.reasoning.done.The sequence number of the event that was emitted.
The ID of the item that was updated.
The index of the output item that was updated.
The index of the reasoning content that was completed.
The final reasoning text that was emitted.
response.reasoning_summary_text.delta
A streaming event that indicated a reasoning summary was incrementally added.
The type of the event, always
response.reasoning_summary.delta.The sequence number of the event that was emitted.
The ID of the item that was updated.
The index of the output item that was updated.
The index of the summary content that was updated.
The summary text delta that was appended.
An obfuscation string that was added to pad the event payload.
response.reasoning_summary_text.done
A streaming event that indicated a reasoning summary was completed.
The type of the event, always
response.reasoning_summary.done.The sequence number of the event that was emitted.
The ID of the item that was updated.
The index of the output item that was updated.
The index of the summary content that was completed.
The final summary text that was emitted.
response.output_text.annotation.added
A streaming event that indicated an output text annotation was added.
The type of the event, always
response.output_text.annotation.added.The sequence number of the event that was emitted.
The ID of the item that was updated.
The index of the output item that was updated.
The index of the output text content that was updated.
The index of the annotation that was added.
An annotation that applies to a span of output text.
Accepted types
response.function_call_arguments.delta
A streaming event that indicated function call arguments were incrementally added.
The type of the event, always
response.function_call_arguments.delta.The sequence number of the event that was emitted.
The ID of the tool call item that was updated.
The index of the output item that was updated.
The arguments delta that was appended.
An obfuscation string that was added to pad the event payload.
response.function_call_arguments.done
A streaming event that indicated function call arguments were completed.
The type of the event, always
response.function_call_arguments.done.The sequence number of the event that was emitted.
The ID of the tool call item that was updated.
The index of the output item that was updated.
The final arguments string that was emitted.
error
A streaming event that indicated an error was emitted.
The type of the event, always
error.The sequence number of the event that was emitted.
The error payload that was emitted.
WebSocket
Open a WebSocket connection and start each turn with a JSON response.create client message. The message uses the
normal response creation body, except HTTP transport fields such as stream, stream_options, and background are not sent. Server progress messages use the
same streaming event objects as text/event-stream
responses, while WebSocket failures use an error
envelope.
Client message
The client event type. Always
response.create.The model to use for this request, e.g. 'gpt-5.2'.
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.
The ID of the response to use as the prior turn for this request.
Allowed 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.
A list of tools that the model may call while generating the response.
Accepted types
Controls which tool the model should use, if any.
Accepted types
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.
Accepted types
Configuration options for text output.
Accepted types
Sampling temperature to use, between 0 and 2. Higher values make the output more
random.
Nucleus sampling parameter, between 0 and 1. The model considers only the tokens
with the top cumulative probability.
Penalizes new tokens based on whether they appear in the text so far.
Penalizes new tokens based on their frequency in the text so far.
Whether the model may call multiple tools in parallel.
The maximum number of tokens the model may generate for this response.
The maximum number of tool calls the model may make while generating the response.
Configuration options for reasoning behavior.
Accepted types
A stable identifier used for safety monitoring and abuse detection.
A key to use when reading from or writing to the prompt cache.
Controls how the service truncates the input when it exceeds the model context
window.
Allowed 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.
Additional instructions to guide the model for this request.
Whether to store the response so it can be retrieved later.
The service tier to use for this request.
Allowed 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.
The number of most likely tokens to return at each position, along with their log
probabilities.
Error message
The event type. Always
error.The HTTP-style status code for the WebSocket error.
The WebSocket error payload.
Compact a response
Return a compacted conversation state object that preserves long-running context without asserting provider-specific compression behavior.
Body parameters
Model ID used to generate the response, like
gpt-5 or o3. OpenAI offers a wide
range of models with different capabilities, performance characteristics, and price
points. Refer to the model guide to browse and compare available
models.Text, image, or file inputs to the model, used to generate a response.
A string is treated as text input with the
user role. An array can contain
one or more input items with different content types.The unique ID of the previous response to the model. Use this to create multi-turn
conversations. Learn more about conversation
state. Cannot be used in conjunction with
conversation.A system (or developer) message inserted into the model's context. When used along
with
previous_response_id, the instructions from a previous response will not be
carried over to the next response. This makes it simple to swap out system (or
developer) messages in new responses.A key to use when reading from or writing to the prompt cache.
Response body
The unique identifier for the compacted response.
The object type. Always
response.compaction.The compacted list of output items.
Unix timestamp (in seconds) when the compacted conversation was created.
Token accounting for the compaction pass, including cached, reasoning, and total
tokens.
API objects
Types used by the request, response, and event schemas.
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.
-
in_progress -
completed -
incomplete
FunctionCallStatus
-
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
-
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
-
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
-
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
-
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
-
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
-
concise - Emit concise summaries of reasoning content.
-
detailed - Emit details summaries of reasoning content.
-
auto - Allow the model to decide when to summarize.
ServiceTierEnum
-
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
-
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
-
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
-
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
ItemField
An item representing a message, tool call, tool output, reasoning, or other response element.
ItemParam
An internal identifier for an item to reference.
TextFormatParam
ToolChoiceParam
Controls which tool the model should use, if any.
Objects
AllowedToolChoice
Allowed 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
The tool choice type. Always
allowed_tools.The list of tools that are permitted for this request.
How to select a tool from the allowed set.
Allowed 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.
Annotation
An annotation that applies to a span of output text.
The type of the URL citation. Always
url_citation.The URL of the web resource.
The index of the first character of the URL citation in the message.
The index of the last character of the URL citation in the message.
The title of the web resource.
AssistantMessageItemParam
The unique ID of this message item.
The item type. Always
message.The role of the message author. Always
assistant.The message content, as a string or an array of content parts.
Accepted types
-
array of -
string
Labels an
assistant message as intermediate commentary (commentary) or the
final answer (final_answer). For models like gpt-5.3-codex and beyond, when
sending follow-up requests, preserve and resend phase on all assistant messages.
Omitting it can degrade performance. Not used for user messages.Allowed values
-
commentary -
final_answer
The status of the message item.
CompactionBody
A compaction item generated by the v1/responses/compact
API.
The type of the item. Always
compaction.The unique ID of the compaction item.
The encrypted content that was produced by compaction.
The identifier of the actor that created the item.
CompactionSummaryItemParam
A compaction item generated by the v1/responses/compact
API.
The ID of the compaction item.
The type of the item. Always
compaction.The encrypted content of the compaction summary.
CompactResource
The unique identifier for the compacted response.
The object type. Always
response.compaction.The compacted list of output items.
Unix timestamp (in seconds) when the compacted conversation was created.
Token accounting for the compaction pass, including cached, reasoning, and total
tokens.
CompactResponseMethodPublicBody
Model ID used to generate the response, like
gpt-5 or o3. OpenAI offers a wide
range of models with different capabilities, performance characteristics, and price
points. Refer to the model guide to browse and compare available
models.Text, image, or file inputs to the model, used to generate a response.
A string is treated as text input with the
user role. An array can contain
one or more input items with different content types.The unique ID of the previous response to the model. Use this to create multi-turn
conversations. Learn more about conversation
state. Cannot be used in conjunction with
conversation.A system (or developer) message inserted into the model's context. When used along
with
previous_response_id, the instructions from a previous response will not be
carried over to the next response. This makes it simple to swap out system (or
developer) messages in new responses.A key to use when reading from or writing to the prompt cache.
CreateResponseBody
The model to use for this request, e.g. 'gpt-5.2'.
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.
The ID of the response to use as the prior turn for this request.
Allowed 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.
A list of tools that the model may call while generating the response.
Accepted types
Controls which tool the model should use, if any.
Accepted types
Allowed 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.
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.
Accepted types
Configuration options for text output.
Accepted types
Sampling temperature to use, between 0 and 2. Higher values make the output more
random.
Nucleus sampling parameter, between 0 and 1. The model considers only the tokens
with the top cumulative probability.
Penalizes new tokens based on whether they appear in the text so far.
Penalizes new tokens based on their frequency in the text so far.
Whether the model may call multiple tools in parallel.
Whether to stream response events as server-sent events.
Options that control streamed response behavior.
Accepted types
Whether to run the request in the background and return immediately.
The maximum number of tokens the model may generate for this response.
The maximum number of tool calls the model may make while generating the response.
Configuration options for reasoning behavior.
Accepted types
A stable identifier used for safety monitoring and abuse detection.
A key to use when reading from or writing to the prompt cache.
Controls how the service truncates the input when it exceeds the model context
window.
Allowed 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.
Additional instructions to guide the model for this request.
Whether to store the response so it can be retrieved later.
The service tier to use for this request.
Allowed 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.
The number of most likely tokens to return at each position, along with their log
probabilities.
DeveloperMessageItemParam
The unique ID of this message item.
The item type. Always
message.The message role. Always
developer.The message content, as a string or an array of content parts.
Accepted types
-
InputTextContentParam[] -
string
The status of the message item.
EmptyModelParam
Error
An error that occurred while generating the response.
A machine-readable error code that was returned.
A human-readable description of the error that was returned.
ErrorPayload
An error payload that was emitted for a streaming error event.
The error type that was emitted.
The error code that was emitted, if any.
The human-readable error message that was emitted.
The parameter name that was associated with the error, if any.
The response headers that were emitted with the error, if any.
ErrorStreamingEvent
A streaming event that indicated an error was emitted.
The type of the event, always
error.The sequence number of the event that was emitted.
The error payload that was emitted.
FunctionCall
A function tool call that was generated by the model.
The type of the item. Always
function_call.The unique ID of the function call item.
The unique ID of the function tool call that was generated.
The name of the function that was called.
The arguments JSON string that was generated.
The status of the function call item that was recorded.
Allowed 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.
FunctionCallItemParam
The unique ID of this function tool call.
The unique ID of the function tool call generated by the model.
The item type. Always
function_call.The name of the function to call.
The function arguments as a JSON string.
The status of the function tool call.
Accepted types
Allowed 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.
The type of the function tool call output. Always
function_call_output.The unique ID of the function tool call output. Populated when this item is
returned via API.
The unique ID of the function tool call generated by the model.
The function tool call output, as a JSON string or an array of text, image,
or file content.
Accepted types
-
string -
array of
The status of the item. One of
in_progress, completed, or incomplete.
Populated when items are returned via API.Allowed values
-
in_progress -
completed -
incomplete
FunctionCallOutputItemParam
The output of a function tool call.
The unique ID of the function tool call output. Populated when this item is
returned via API.
The unique ID of the function tool call generated by the model.
The type of the function tool call output. Always
function_call_output.The function tool call output, as a JSON string or an array of text, image,
or file content.
Accepted types
The status of the item. One of
in_progress, completed, or incomplete.
Populated when items are returned via API.Accepted types
Allowed 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.
The type of the function tool. Always
function.The name of the function to call.
A description of the function. Used by the model to determine whether or not to
call the function.
A JSON schema object describing the parameters of the function.
Whether to enforce strict parameter validation. Default
true.FunctionToolChoice
FunctionToolParam
IncompleteDetails
Details about why the response was incomplete.
The reason the response could not be completed.
InputFileContent
A file input to the model.
The type of the input item. Always
input_file.The name of the file to be sent to the model.
The URL of the file to be sent to the model.
InputFileContentParam
A file input to the model.
The type of the input item. Always
input_file.The name of the file to be sent to the model.
The base64-encoded data of the file to be sent to the model.
The URL of the file to be sent to the model.
InputImageContent
An image input to the model. Learn about image inputs.
The type of the input item. Always
input_image.The URL of the image to be sent to the model. A fully qualified URL or base64
encoded image in a data URL.
The detail level of the image to be sent to the model. One of
high, low, or
auto. Defaults to auto.Allowed 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
The type of the input item. Always
input_image.The URL of the image to be sent to the model. A fully qualified URL or base64
encoded image in a data URL.
The detail level of the image to be sent to the model. One of
high, low, or
auto. Defaults to auto.Accepted types
Allowed 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.
The type of the input item. Always
input_text.The text input to the model.
InputTextContentParam
A text input to the model.
The type of the input item. Always
input_text.The text input to the model.
InputTokensDetails
A breakdown of input token usage that was recorded.
The number of input tokens that were served from cache.
InputVideoContent
A content block representing a video input to the model.
The type of the input content. Always
input_video.A base64 or remote url that resolves to a video file.
ItemReferenceParam
An internal identifier for an item to reference.
The type of item to reference. Always
item_reference.The ID of the item to reference.
JsonObjectResponseFormat
JsonSchemaResponseFormat
JsonSchemaResponseFormatParam
The type of response format being defined. Always
json_schema.A description of what the response format is for, used by the model to determine
how to respond in the format.
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.
The schema for the response format, described as a JSON Schema object.
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.
Message
A message to or from the model.
The type of the message. Always set to
message.The unique ID of the message.
The status of item. One of
in_progress, completed, or incomplete. Populated
when items are returned via API.Allowed 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.
The role of the message. One of
unknown, user, assistant, system, critic,
discriminator, developer, or tool.Allowed 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.
The content of the message
Labels an
assistant message as intermediate commentary (commentary) or the
final answer (final_answer). For models like gpt-5.3-codex and beyond, when
sending follow-up requests, preserve and resend phase on all assistant messages.
Omitting it can degrade performance. Not used for user messages.Allowed values
-
commentary -
final_answer
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.
The type of the output text. Always
output_text.The text output from the model.
The annotations of the text output.
OutputTextContentParam
The content type. Always
output_text.The text content.
Citations associated with the text content.
OutputTokensDetails
A breakdown of output token usage that was recorded.
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.
Accepted types
Allowed 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.
Accepted types
Allowed values
-
concise - Emit concise summaries of reasoning content.
-
detailed - Emit details summaries of reasoning content.
-
auto - Allow the model to decide when to summarize.
ReasoningBody
A reasoning item that was generated by the model.
The type of the item. Always
reasoning.The unique ID of the reasoning item.
The reasoning content that was generated.
The reasoning summary content that was generated.
The encrypted reasoning content that was generated.
ReasoningItemParam
The unique ID of this reasoning item.
The item type. Always
reasoning.Reasoning summary content associated with this item.
An encrypted representation of the reasoning content.
ReasoningParam
gpt-5 and o-series models only Configuration options for reasoning models.
Controls the level of reasoning effort the model should apply. Higher effort may
increase latency and cost.
Accepted types
Allowed 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.
Controls whether the response includes a reasoning summary.
Accepted types
Allowed 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
The content type. Always
summary_text.The reasoning summary text.
ReasoningTextContent
Reasoning text from the model.
The type of the reasoning text. Always
reasoning_text.The reasoning text from the model.
RefusalContent
A refusal from the model.
The type of the refusal. Always
refusal.The refusal explanation from the model.
RefusalContentParam
The content type. Always
refusal.The refusal text.
ResponseCompletedStreamingEvent
A streaming event that indicated the response was completed.
The type of the event, always
response.completed.The sequence number of the event that was emitted.
The response snapshot that was emitted with the event.
ResponseContentPartAddedStreamingEvent
A streaming event that indicated a content part was added.
The type of the event, always
response.content_part.added.The sequence number of the event that was emitted.
The ID of the item that was updated.
The index of the output item that was updated.
The index of the content part that was added.
A content part that makes up an input or output item.
ResponseContentPartDoneStreamingEvent
A streaming event that indicated a content part was completed.
The type of the event, always
response.content_part.done.The sequence number of the event that was emitted.
The ID of the item that was updated.
The index of the output item that was updated.
The index of the content part that was completed.
A content part that makes up an input or output item.
ResponseCreatedStreamingEvent
A streaming event that indicated the response was created.
The type of the event, always
response.created.The sequence number of the event that was emitted.
The response snapshot that was emitted with the event.
ResponseFailedStreamingEvent
A streaming event that indicated the response had failed.
The type of the event, always
response.failed.The sequence number of the event that was emitted.
The response snapshot that was emitted with the event.
ResponseFunctionCallArgumentsDeltaStreamingEvent
A streaming event that indicated function call arguments were incrementally added.
The type of the event, always
response.function_call_arguments.delta.The sequence number of the event that was emitted.
The ID of the tool call item that was updated.
The index of the output item that was updated.
The arguments delta that was appended.
An obfuscation string that was added to pad the event payload.
ResponseFunctionCallArgumentsDoneStreamingEvent
A streaming event that indicated function call arguments were completed.
The type of the event, always
response.function_call_arguments.done.The sequence number of the event that was emitted.
The ID of the tool call item that was updated.
The index of the output item that was updated.
The final arguments string that was emitted.
ResponseIncompleteStreamingEvent
A streaming event that indicated the response was incomplete.
The type of the event, always
response.incomplete.The sequence number of the event that was emitted.
The response snapshot that was emitted with the event.
ResponseInProgressStreamingEvent
A streaming event that indicated the response was in progress.
The type of the event, always
response.in_progress.The sequence number of the event that was emitted.
The response snapshot that was emitted with the event.
ResponseOutputItemAddedStreamingEvent
A streaming event that indicated an output item was added to the response.
The type of the event, always
response.output_item.added.The sequence number of the event that was emitted.
The index of the output item that was added.
An item representing a message, tool call, tool output, reasoning, or other
response element.
Accepted types
ResponseOutputItemDoneStreamingEvent
A streaming event that indicated an output item was completed.
The type of the event, always
response.output_item.done.The sequence number of the event that was emitted.
The index of the output item that was completed.
An item representing a message, tool call, tool output, reasoning, or other
response element.
Accepted types
ResponseOutputTextAnnotationAddedStreamingEvent
A streaming event that indicated an output text annotation was added.
The type of the event, always
response.output_text.annotation.added.The sequence number of the event that was emitted.
The ID of the item that was updated.
The index of the output item that was updated.
The index of the output text content that was updated.
The index of the annotation that was added.
An annotation that applies to a span of output text.
Accepted types
ResponseOutputTextDeltaStreamingEvent
A streaming event that indicated output text was incrementally added.
The type of the event, always
response.output_text.delta.The sequence number of the event that was emitted.
The ID of the item that was updated.
The index of the output item that was updated.
The index of the content part that was updated.
The text delta that was appended.
The token log probabilities that were emitted with the delta, if any.
An obfuscation string that was added to pad the event payload.
ResponseOutputTextDoneStreamingEvent
A streaming event that indicated output text was completed.
The type of the event, always
response.output_text.done.The sequence number of the event that was emitted.
The ID of the item that was updated.
The index of the output item that was updated.
The index of the content part that was completed.
The final text that was emitted.
The token log probabilities that were emitted with the final text, if any.
ResponseQueuedStreamingEvent
A streaming event that indicated the response was queued.
The type of the event, always
response.queued.The sequence number of the event that was emitted.
The response snapshot that was emitted with the event.
ResponseReasoningDeltaStreamingEvent
A streaming event that indicated reasoning text was incrementally added.
The type of the event, always
response.reasoning.delta.The sequence number of the event that was emitted.
The ID of the item that was updated.
The index of the output item that was updated.
The index of the reasoning content that was updated.
The reasoning text delta that was appended.
An obfuscation string that was added to pad the event payload.
ResponseReasoningDoneStreamingEvent
A streaming event that indicated reasoning text was completed.
The type of the event, always
response.reasoning.done.The sequence number of the event that was emitted.
The ID of the item that was updated.
The index of the output item that was updated.
The index of the reasoning content that was completed.
The final reasoning text that was emitted.
ResponseReasoningSummaryDeltaStreamingEvent
A streaming event that indicated a reasoning summary was incrementally added.
The type of the event, always
response.reasoning_summary.delta.The sequence number of the event that was emitted.
The ID of the item that was updated.
The index of the output item that was updated.
The index of the summary content that was updated.
The summary text delta that was appended.
An obfuscation string that was added to pad the event payload.
ResponseReasoningSummaryDoneStreamingEvent
A streaming event that indicated a reasoning summary was completed.
The type of the event, always
response.reasoning_summary.done.The sequence number of the event that was emitted.
The ID of the item that was updated.
The index of the output item that was updated.
The index of the summary content that was completed.
The final summary text that was emitted.
ResponseReasoningSummaryPartAddedStreamingEvent
A streaming event that indicated a reasoning summary part was added.
The type of the event, always
response.reasoning_summary_part.added.The sequence number of the event that was emitted.
The ID of the item that was updated.
The index of the output item that was updated.
The index of the summary part that was added.
A content part that makes up an input or output item.
ResponseReasoningSummaryPartDoneStreamingEvent
A streaming event that indicated a reasoning summary part was completed.
The type of the event, always
response.reasoning_summary_part.done.The sequence number of the event that was emitted.
The ID of the item that was updated.
The index of the output item that was updated.
The index of the summary part that was completed.
A content part that makes up an input or output item.
ResponseRefusalDeltaStreamingEvent
A streaming event that indicated refusal text was incrementally added.
The type of the event, always
response.refusal.delta.The sequence number of the event that was emitted.
The ID of the item that was updated.
The index of the output item that was updated.
The index of the refusal content that was updated.
The refusal text delta that was appended.
ResponseRefusalDoneStreamingEvent
A streaming event that indicated refusal text was completed.
The type of the event, always
response.refusal.done.The sequence number of the event that was emitted.
The ID of the item that was updated.
The index of the output item that was updated.
The index of the refusal content that was completed.
The final refusal text that was emitted.
ResponseResource
The complete response object that was returned by the Responses API.
The unique ID of the response that was created.
The object type, which was always
response.The Unix timestamp (in seconds) for when the response was created.
The Unix timestamp (in seconds) for when the response was completed, if it was
completed.
The status that was set for the response.
Details about why the response was incomplete, if applicable.
Accepted types
The model that generated this response.
The ID of the previous response in the chain that was referenced, if any.
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.
Accepted types
The tools that were available to the model during response generation.
Accepted types
Allowed 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.
How the input was truncated by the service when it exceeded the model context
window.
Allowed 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.
Whether the model was allowed to call multiple tools in parallel.
Configuration options for text output that were used.
The nucleus sampling parameter that was used for this response.
The presence penalty that was used to penalize new tokens based on whether they
appear in the text so far.
The frequency penalty that was used to penalize new tokens based on their frequency
in the text so far.
The number of most likely tokens that were returned at each position, along with
their log probabilities.
The sampling temperature that was used for this response.
Reasoning configuration and outputs that were produced for this response.
Accepted types
Token usage statistics that were recorded for the response, if available.
Accepted types
The maximum number of tokens the model was allowed to generate for this response.
The maximum number of tool calls the model was allowed to make while generating the
response.
Whether this response was stored so it can be retrieved later.
Whether this request was run in the background.
The service tier that was used for this response.
Developer-defined metadata that was associated with the response.
A stable identifier that was used for safety monitoring and abuse detection.
A key that was used to read from or write to the prompt cache.
ResponsesToolParam
SpecificFunctionParam
The tool to call. Always
function.The name of the function tool to call.
SpecificToolChoiceParam
The tool to call. Always
function.The name of the function tool to call.
StreamOptionsParam
Options that control streamed response behavior.
Whether to obfuscate sensitive information in streamed output. Defaults to
true.SummaryTextContent
A summary text from the model.
The type of the object. Always
summary_text.A summary of the reasoning output from the model so far.
SystemMessageItemParam
The unique ID of this message item.
The item type. Always
message.The message role. Always
system.The message content, as a string or an array of content parts.
Accepted types
-
InputTextContentParam[] -
string
The status of the message item.
TextContent
A text content.
TextField
Accepted types
Allowed 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.
Accepted types
Controls the level of detail in generated text output.
Allowed 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
Tool
A tool that can be used to generate a response.
The type of the function tool. Always
function.The name of the function to call.
A description of the function. Used by the model to determine whether or not to
call the function.
A JSON schema object describing the parameters of the function.
Whether to enforce strict parameter validation. Default
true.TopLogProb
The top log probability of a token.
UrlCitationBody
A citation for a web resource used to generate a model response.
The type of the URL citation. Always
url_citation.The URL of the web resource.
The index of the first character of the URL citation in the message.
The index of the last character of the URL citation in the message.
The title of the web resource.
UrlCitationParam
The citation type. Always
url_citation.The index of the first character of the citation in the message.
The index of the last character of the citation in the message.
The URL of the cited resource.
The title of the cited resource.
Usage
Token usage statistics that were recorded for the response.
The number of input tokens that were used to generate the response.
The number of output tokens that were generated by the model.
The total number of tokens that were used.
A breakdown of input token usage that was recorded.
A breakdown of output token usage that was recorded.
UserMessageItemParam
The unique ID of this message item.
The item type. Always
message.The message role. Always
user.The message content, as a string or an array of content parts.
Accepted types
The status of the message item.
WebSocketErrorEvent
A WebSocket error envelope returned for Responses WebSocket mode failures.
The event type. Always
error.The HTTP-style status code for the WebSocket error.
The WebSocket error payload.
WebSocketResponseCreateEvent
A client-sent WebSocket event that starts a Responses turn. It uses the normal
response-create body plus a required type field.
The client event type. Always
response.create.The model to use for this request, e.g. 'gpt-5.2'.
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.
The ID of the response to use as the prior turn for this request.
Allowed 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.
A list of tools that the model may call while generating the response.
Accepted types
Controls which tool the model should use, if any.
Accepted types
Allowed 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.
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.
Accepted types
Configuration options for text output.
Accepted types
Sampling temperature to use, between 0 and 2. Higher values make the output more
random.
Nucleus sampling parameter, between 0 and 1. The model considers only the tokens
with the top cumulative probability.
Penalizes new tokens based on whether they appear in the text so far.
Penalizes new tokens based on their frequency in the text so far.
Whether the model may call multiple tools in parallel.
The maximum number of tokens the model may generate for this response.
The maximum number of tool calls the model may make while generating the response.
Configuration options for reasoning behavior.
Accepted types
A stable identifier used for safety monitoring and abuse detection.
A key to use when reading from or writing to the prompt cache.
Controls how the service truncates the input when it exceeds the model context
window.
Allowed 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.
Additional instructions to guide the model for this request.
Whether to store the response so it can be retrieved later.
The service tier to use for this request.
Allowed 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.
The number of most likely tokens to return at each position, along with their log
probabilities.