Create a model response

POSThttps:/api.openai.com/v1/responses

Creates a model response. Provide text or image inputs to generate text or JSON outputs. Have the model call your own custom code or use built-in tools like web search or file search to use your own data as input for the model's response.

Request body

metadata
object or null
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.
temperature
number or null
Defaults: 1
What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or top_p but not both.
top_p
number or null
Defaults: 1
An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered.
We generally recommend altering this or temperature but not both.
user
string
A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. Learn more.
service_tier
string or null
Defaults: auto
Specifies the latency tier to use for processing the request. This parameter is relevant for customers subscribed to the scale tier service:
- If set to 'auto', and the Project is Scale tier enabled, the system will utilize scale tier credits until they are exhausted.
- If set to 'auto', and the Project is not Scale tier enabled, the request will be processed using the default service tier with a lower uptime SLA and no latency guarentee.
- If set to 'default', the request will be processed using the default service tier with a lower uptime SLA and no latency guarentee.
- If set to 'flex', the request will be processed with the Flex Processing service tier. Learn more.
- When not set, the default behavior is 'auto'.
When this parameter is set, the response body will include the service_tier utilized.
- auto
  string
- default
  string
- flex
  string
previous_response_id
string or null
The unique ID of the previous response to the model. Use this to create multi-turn conversations. Learn more about conversation state.
model
string
Model ID used to generate the response, like gpt-4o 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.
- model
  string
- model
  string
  gpt-4.1
  string
  gpt-4.1-mini
  string
  gpt-4.1-nano
  string
  gpt-4.1-2025-04-14
  string
  gpt-4.1-mini-2025-04-14
  string
  gpt-4.1-nano-2025-04-14
  string
  o4-mini
  string
  o4-mini-2025-04-16
  string
  o3
  string
  o3-2025-04-16
  string
  o3-mini
  string
  o3-mini-2025-01-31
  string
  o1
  string
  o1-2024-12-17
  string
  o1-preview
  string
  o1-preview-2024-09-12
  string
  o1-mini
  string
  o1-mini-2024-09-12
  string
  gpt-4o
  string
  gpt-4o-2024-11-20
  string
  gpt-4o-2024-08-06
  string
  gpt-4o-2024-05-13
  string
  gpt-4o-audio-preview
  string
  gpt-4o-audio-preview-2024-10-01
  string
  gpt-4o-audio-preview-2024-12-17
  string
  gpt-4o-mini-audio-preview
  string
  gpt-4o-mini-audio-preview-2024-12-17
  string
  gpt-4o-search-preview
  string
  gpt-4o-mini-search-preview
  string
  gpt-4o-search-preview-2025-03-11
  string
  gpt-4o-mini-search-preview-2025-03-11
  string
  chatgpt-4o-latest
  string
  gpt-4o-mini
  string
  gpt-4o-mini-2024-07-18
  string
  gpt-4-turbo
  string
  gpt-4-turbo-2024-04-09
  string
  gpt-4-0125-preview
  string
  gpt-4-turbo-preview
  string
  gpt-4-1106-preview
  string
  gpt-4-vision-preview
  string
  gpt-4
  string
  gpt-4-0314
  string
  gpt-4-0613
  string
  gpt-4-32k
  string
  gpt-4-32k-0314
  string
  gpt-4-32k-0613
  string
  gpt-3.5-turbo
  string
  gpt-3.5-turbo-16k
  string
  gpt-3.5-turbo-0301
  string
  gpt-3.5-turbo-0613
  string
  gpt-3.5-turbo-1106
  string
  gpt-3.5-turbo-0125
  string
  gpt-3.5-turbo-16k-0613
  string
- ResponsesOnlyModel
  string
  o1-pro
  string
  o1-pro-2025-03-19
  string
  computer-use-preview
  string
  computer-use-preview-2025-03-11
  string
reasoning
object or null
o-series models only
Configuration options for reasoning models.
- effort
  string or null
  Defaults: medium
  o-series models only
  Constrains effort on reasoning for reasoning models. Currently supported values are low, medium, and high. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response.
  low
  string
  medium
  string
  high
  string
- summary
  string or null
  A summary of the reasoning performed by the model. This can be useful for debugging and understanding the model's reasoning process. One of auto, concise, or detailed.
  auto
  string
  concise
  string
  detailed
  string
- generate_summary
  string or null
  Deprecated
  Deprecated: use summary instead.
  A summary of the reasoning performed by the model. This can be useful for debugging and understanding the model's reasoning process. One of auto, concise, or detailed.
  auto
  string
  concise
  string
  detailed
  string
max_output_tokens
integer or null
An upper bound for the number of tokens that can be generated for a response, including visible output tokens and reasoning tokens.
instructions
string or null
Inserts a system (or developer) message as the first item in the model's context.
When using 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.
text
object
Configuration options for a text response from the model. Can be plain text or structured JSON data. Learn more:
- Text inputs and outputs
- Structured Outputs
- format
  object
  An object specifying the format that the model must output.
  Configuring enables Structured Outputs, which ensures the model will match your supplied JSON schema. Learn more in the Structured Outputs guide.
  The default format is with no additional options.
  Not recommended for gpt-4o and newer models:
  Setting to enables the older JSON mode, which ensures the message the model generates is valid JSON. Using json_schema is preferred for models that support it.
  Text
  object
  Default response format. Used to generate text responses.
  type
  string
  Required
  The type of response format being defined. Always text.
  text
  string
  JSON schema
  object
  JSON Schema response format. Used to generate structured JSON responses. Learn more about Structured Outputs.
  type
  string
  Required
  The type of response format being defined. Always json_schema.
  json_schema
  string
  description
  string
  A description of what the response format is for, used by the model to determine how to respond in the format.
  name
  string
  Required
  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.
  schema
  object
  Required
  The schema for the response format, described as a JSON Schema object. Learn how to build JSON schemas here.
  strict
  boolean or null
  Defaults: false
  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. To learn more, read the Structured Outputs guide.
  JSON object
  object
  JSON object response format. An older method of generating JSON responses. Using json_schema is recommended for models that support it. Note that the model will not generate JSON without a system or user message instructing it to do so.
  type
  string
  Required
  The type of response format being defined. Always json_object.
  json_object
  string
tools
array
An array of tools the model may call while generating a response. You can specify which tool to use by setting the tool_choice parameter.
The two categories of tools you can provide the model are:
- Built-in tools: Tools that are provided by OpenAI that extend the model's capabilities, like web search or file search. Learn more about built-in tools.
- Function calls (custom tools): Functions that are defined by you, enabling the model to call your own code. Learn more about function calling.
- File search
  object
  A tool that searches for relevant content from uploaded files. Learn more about the file search tool.
  type
  string
  Required
  Defaults: file_search
  The type of the file search tool. Always file_search.
  file_search
  string
  vector_store_ids
  array
  Required
  The IDs of the vector stores to search.
  items
  string
  max_num_results
  integer
  The maximum number of results to return. This number should be between 1 and 50 inclusive.
  ranking_options
  object
  Ranking options for search.
  ranker
  string
  The ranker to use for the file search.
  auto
  string
  default-2024-11-15
  string
  score_threshold
  number
  The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results.
  filters
  object or null
  Comparison Filter
  object
  A filter used to compare a specified attribute key to a given value using a defined comparison operation.
  type
  string
  Required
  Defaults: eq
  Specifies the comparison operator: eq, ne, gt, gte, lt, lte.
  eq: equals
  ne: not equal
  gt: greater than
  gte: greater than or equal
  lt: less than
  lte: less than or equal
  eq
  string
  ne
  string
  gt
  string
  gte
  string
  lt
  string
  lte
  string
  key
  string
  Required
  The key to compare against the value.
  value
  string or number or boolean
  The value to compare against the attribute key; supports string, number, or boolean types.
  value
  string
  Required
  value
  number
  Required
  value
  boolean
  Required
  Compound Filter
  object
  Combine multiple filters using and or or.
  type
  string
  Required
  Type of operation: and or or.
  and
  string
  or
  string
  filters
  array
  Required
  Array of filters to combine. Items can be ComparisonFilter or CompoundFilter.
  Comparison Filter
  object
  A filter used to compare a specified attribute key to a given value using a defined comparison operation.
  type
  string
  Required
  Defaults: eq
  Specifies the comparison operator: eq, ne, gt, gte, lt, lte.
  eq: equals
  ne: not equal
  gt: greater than
  gte: greater than or equal
  lt: less than
  lte: less than or equal
  eq
  string
  ne
  string
  gt
  string
  gte
  string
  lt
  string
  lte
  string
  key
  string
  Required
  The key to compare against the value.
  value
  string or number or boolean
  The value to compare against the attribute key; supports string, number, or boolean types.
  value
  string
  Required
  value
  number
  Required
  value
  boolean
  Required
  items
  object
  filters
  null
- Function
  object
  Defines a function in your own code the model can choose to call. Learn more about function calling.
  type
  string
  Required
  Defaults: function
  The type of the function tool. Always function.
  function
  string
  name
  string
  Required
  The name of the function to call.
  description
  string or null
  description
  string
  A description of the function. Used by the model to determine whether or not to call the function.
  description
  null
  parameters
  object or null
  parameters
  object
  Required
  A JSON schema object describing the parameters of the function.
  parameters
  null
  Required
  strict
  boolean or null
  strict
  boolean
  Required
  Whether to enforce strict parameter validation. Default true.
  strict
  null
  Required
- Web search preview
  object
  This tool searches the web for relevant results to use in a response. Learn more about the web search tool.
  type
  string
  Required
  Defaults: web_search_preview
  The type of the web search tool. One of web_search_preview or web_search_preview_2025_03_11.
  web_search_preview
  string
  web_search_preview_2025_03_11
  string
  user_location
  object or null
  user_location
  object
  The user's location.
  type
  string
  Required
  Defaults: approximate
  The type of location approximation. Always approximate.
  approximate
  string
  country
  string or null
  country
  string
  The two-letter ISO country code of the user, e.g. US.
  country
  null
  region
  string or null
  region
  string
  Free text input for the region of the user, e.g. California.
  region
  null
  city
  string or null
  city
  string
  Free text input for the city of the user, e.g. San Francisco.
  city
  null
  timezone
  string or null
  timezone
  string
  The IANA timezone of the user, e.g. America/Los_Angeles.
  timezone
  null
  user_location
  null
  search_context_size
  string
  High level guidance for the amount of context window space to use for the search. One of low, medium, or high. medium is the default.
  low
  string
  medium
  string
  high
  string
- Computer use preview
  object
  A tool that controls a virtual computer. Learn more about the computer tool.
  type
  string
  Required
  Defaults: computer_use_preview
  The type of the computer use tool. Always computer_use_preview.
  computer_use_preview
  string
  environment
  string
  Required
  The type of computer environment to control.
  windows
  string
  mac
  string
  linux
  string
  ubuntu
  string
  browser
  string
  display_width
  integer
  Required
  The width of the computer display.
  display_height
  integer
  Required
  The height of the computer display.
tool_choice
string or object
How the model should select which tool (or tools) to use when generating a response. See the tools parameter to see how to specify which tools the model can call.
- Tool choice mode
  string
  Controls which (if any) tool is called by the model.
  none means the model will not call any tool and instead generates a message.
  auto means the model can pick between generating a message or calling one or more tools.
  required means the model must call one or more tools.
  none
  string
  auto
  string
  required
  string
- Hosted tool
  object
  Indicates that the model should use a built-in tool to generate a response. Learn more about built-in tools.
  type
  string
  Required
  The type of hosted tool the model should to use. Learn more about built-in tools.
  Allowed values are:
  file_search
  web_search_preview
  computer_use_preview
  file_search
  string
  web_search_preview
  string
  computer_use_preview
  string
  web_search_preview_2025_03_11
  string
- Function tool
  object
  Use this option to force the model to call a specific function.
  type
  string
  Required
  For function calling, the type is always function.
  function
  string
  name
  string
  Required
  The name of the function to call.
truncation
string or null
Defaults: disabled
The truncation strategy to use for the model response.
- auto: If the context of this response and previous ones exceeds the model's context window size, the model will truncate the response to fit the context window by dropping input items in the middle of the conversation.
- disabled (default): If a model response will exceed the context window size for a model, the request will fail with a 400 error.
- auto
  string
- disabled
  string
input
string or array
Text, image, or file inputs to the model, used to generate a response.
Learn more:
- Text input
  string
  Required
  A text input to the model, equivalent to a text input with the user role.
- Input item list
  array
  Required
  A list of one or many input items to the model, containing different content types.
  Input message
  object
  A message input to the model with a role indicating instruction following hierarchy. Instructions given with the developer or system role take precedence over instructions given with the user role. Messages with the assistant role are presumed to have been generated by the model in previous interactions.
  role
  string
  Required
  The role of the message input. One of user, assistant, system, or developer.
  user
  string
  assistant
  string
  system
  string
  developer
  string
  content
  string or array
  Text, image, or audio input to the model, used to generate a response. Can also contain previous assistant responses.
  Text input
  string
  Required
  A text input to the model.
  Input item content list
  array
  Required
  A list of one or many input items to the model, containing different content types.
  Input text
  object
  A text input to the model.
  type
  string
  Required
  Defaults: input_text
  The type of the input item. Always input_text.
  input_text
  string
  text
  string
  Required
  The text input to the model.
  Input image
  object
  An image input to the model. Learn about image inputs.
  type
  string
  Required
  Defaults: input_image
  The type of the input item. Always input_image.
  input_image
  string
  image_url
  string or null
  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.
  image_url
  null
  file_id
  string or null
  file_id
  string
  The ID of the file to be sent to the model.
  file_id
  null
  detail
  string
  Required
  The detail level of the image to be sent to the model. One of high, low, or auto. Defaults to auto.
  low
  string
  high
  string
  auto
  string
  Input file
  object
  A file input to the model.
  type
  string
  Required
  Defaults: input_file
  The type of the input item. Always input_file.
  input_file
  string
  file_id
  string or null
  file_id
  string
  The ID of the file to be sent to the model.
  file_id
  null
  filename
  string
  The name of the file to be sent to the model.
  file_data
  string
  The content of the file to be sent to the model.
  type
  string
  The type of the message input. Always message.
  message
  string
  Input message
  object
  A message input to the model with a role indicating instruction following hierarchy. Instructions given with the developer or system role take precedence over instructions given with the user role.
  type
  string
  The type of the message input. Always set to message.
  message
  string
  role
  string
  Required
  The role of the message input. One of user, system, or developer.
  user
  string
  system
  string
  developer
  string
  status
  string
  The status of item. One of in_progress, completed, or incomplete. Populated when items are returned via API.
  in_progress
  string
  completed
  string
  incomplete
  string
  content
  array
  Required
  A list of one or many input items to the model, containing different content types.
  Input text
  object
  A text input to the model.
  type
  string
  Required
  Defaults: input_text
  The type of the input item. Always input_text.
  input_text
  string
  text
  string
  Required
  The text input to the model.
  Input image
  object
  An image input to the model. Learn about image inputs.
  type
  string
  Required
  Defaults: input_image
  The type of the input item. Always input_image.
  input_image
  string
  image_url
  string or null
  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.
  image_url
  null
  file_id
  string or null
  file_id
  string
  The ID of the file to be sent to the model.
  file_id
  null
  detail
  string
  Required
  The detail level of the image to be sent to the model. One of high, low, or auto. Defaults to auto.
  low
  string
  high
  string
  auto
  string
  Input file
  object
  A file input to the model.
  type
  string
  Required
  Defaults: input_file
  The type of the input item. Always input_file.
  input_file
  string
  file_id
  string or null
  file_id
  string
  The ID of the file to be sent to the model.
  file_id
  null
  filename
  string
  The name of the file to be sent to the model.
  file_data
  string
  The content of the file to be sent to the model.
  Output message
  object
  An output message from the model.
  id
  string
  Required
  The unique ID of the output message.
  type
  string
  Required
  The type of the output message. Always message.
  message
  string
  role
  string
  Required
  The role of the output message. Always assistant.
  assistant
  string
  content
  array
  Required
  The content of the output message.
  Output text
  object
  A text output from the model.
  type
  string
  Required
  Defaults: output_text
  The type of the output text. Always output_text.
  output_text
  string
  text
  string
  Required
  The text output from the model.
  annotations
  array
  Required
  The annotations of the text output.
  File citation
  object
  A citation to a file.
  type
  string
  Required
  Defaults: file_citation
  The type of the file citation. Always file_citation.
  file_citation
  string
  file_id
  string
  Required
  The ID of the file.
  index
  integer
  Required
  The index of the file in the list of files.
  URL citation
  object
  A citation for a web resource used to generate a model response.
  type
  string
  Required
  Defaults: url_citation
  The type of the URL citation. Always url_citation.
  url_citation
  string
  url
  string
  Required
  The URL of the web resource.
  start_index
  integer
  Required
  The index of the first character of the URL citation in the message.
  end_index
  integer
  Required
  The index of the last character of the URL citation in the message.
  title
  string
  Required
  The title of the web resource.
  File path
  object
  A path to a file.
  type
  string
  Required
  The type of the file path. Always file_path.
  file_path
  string
  file_id
  string
  Required
  The ID of the file.
  index
  integer
  Required
  The index of the file in the list of files.
  Refusal
  object
  A refusal from the model.
  type
  string
  Required
  Defaults: refusal
  The type of the refusal. Always refusal.
  refusal
  string
  refusal
  string
  Required
  The refusal explanationfrom the model.
  status
  string
  Required
  The status of the message input. One of in_progress, completed, or incomplete. Populated when input items are returned via API.
  in_progress
  string
  completed
  string
  incomplete
  string
  File search tool call
  object
  The results of a file search tool call. See the file search guide for more information.
  id
  string
  Required
  The unique ID of the file search tool call.
  type
  string
  Required
  The type of the file search tool call. Always file_search_call.
  file_search_call
  string
  status
  string
  Required
  The status of the file search tool call. One of in_progress, searching, incomplete or failed,
  in_progress
  string
  searching
  string
  completed
  string
  incomplete
  string
  failed
  string
  queries
  array
  Required
  The queries used to search for files.
  items
  string
  results
  array or null
  The results of the file search tool call.
  items
  object
  file_id
  string
  The unique ID of the file.
  text
  string
  The text that was retrieved from the file.
  filename
  string
  The name of the file.
  attributes
  object or null
  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, booleans, or numbers.
  score
  number
  The relevance score of the file - a value between 0 and 1.
  Computer tool call
  object
  A tool call to a computer use tool. See the computer use guide for more information.
  type
  string
  Required
  Defaults: computer_call
  The type of the computer call. Always computer_call.
  computer_call
  string
  id
  string
  Required
  The unique ID of the computer call.
  call_id
  string
  Required
  An identifier used when responding to the tool call with output.
  action
  object
  Click
  object
  Required
  A click action.
  type
  string
  Required
  Defaults: click
  Specifies the event type. For a click action, this property is always set to click.
  click
  string
  button
  string
  Required
  Indicates which mouse button was pressed during the click. One of left, right, wheel, back, or forward.
  left
  string
  right
  string
  wheel
  string
  back
  string
  forward
  string
  x
  integer
  Required
  The x-coordinate where the click occurred.
  y
  integer
  Required
  The y-coordinate where the click occurred.
  DoubleClick
  object
  Required
  A double click action.
  type
  string
  Required
  Defaults: double_click
  Specifies the event type. For a double click action, this property is always set to double_click.
  double_click
  string
  x
  integer
  Required
  The x-coordinate where the double click occurred.
  y
  integer
  Required
  The y-coordinate where the double click occurred.
  Drag
  object
  Required
  A drag action.
  type
  string
  Required
  Defaults: drag
  Specifies the event type. For a drag action, this property is always set to drag.
  drag
  string
  path
  array
  Required
  An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg
  items
  object
  A series of x/y coordinate pairs in the drag path.
  x
  integer
  Required
  The x-coordinate.
  y
  integer
  Required
  The y-coordinate.
  KeyPress
  object
  Required
  A collection of keypresses the model would like to perform.
  type
  string
  Required
  Defaults: keypress
  Specifies the event type. For a keypress action, this property is always set to keypress.
  keypress
  string
  keys
  array
  Required
  The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key.
  items
  string
  One of the keys the model is requesting to be pressed.
  Move
  object
  Required
  A mouse move action.
  type
  string
  Required
  Defaults: move
  Specifies the event type. For a move action, this property is always set to move.
  move
  string
  x
  integer
  Required
  The x-coordinate to move to.
  y
  integer
  Required
  The y-coordinate to move to.
  Screenshot
  object
  Required
  A screenshot action.
  type
  string
  Required
  Defaults: screenshot
  Specifies the event type. For a screenshot action, this property is always set to screenshot.
  screenshot
  string
  Scroll
  object
  Required
  A scroll action.
  type
  string
  Required
  Defaults: scroll
  Specifies the event type. For a scroll action, this property is always set to scroll.
  scroll
  string
  x
  integer
  Required
  The x-coordinate where the scroll occurred.
  y
  integer
  Required
  The y-coordinate where the scroll occurred.
  scroll_x
  integer
  Required
  The horizontal scroll distance.
  scroll_y
  integer
  Required
  The vertical scroll distance.
  Type
  object
  Required
  An action to type in text.
  type
  string
  Required
  Defaults: type
  Specifies the event type. For a type action, this property is always set to type.
  type
  string
  text
  string
  Required
  The text to type.
  Wait
  object
  Required
  A wait action.
  type
  string
  Required
  Defaults: wait
  Specifies the event type. For a wait action, this property is always set to wait.
  wait
  string
  pending_safety_checks
  array
  Required
  The pending safety checks for the computer call.
  items
  object
  A pending safety check for the computer call.
  id
  string
  Required
  The ID of the pending safety check.
  code
  string
  Required
  The type of the pending safety check.
  message
  string
  Required
  Details about the pending safety check.
  status
  string
  Required
  The status of the item. One of in_progress, completed, or incomplete. Populated when items are returned via API.
  in_progress
  string
  completed
  string
  incomplete
  string
  Computer tool call output
  object
  The output of a computer tool call.
  id
  string or null
  id
  string
  The ID of the computer tool call output.
  id
  null
  call_id
  string
  Required
  The ID of the computer tool call that produced the output.
  type
  string
  Required
  Defaults: computer_call_output
  The type of the computer tool call output. Always computer_call_output.
  computer_call_output
  string
  output
  object
  Required
  A computer screenshot image used with the computer use tool.
  type
  string
  Required
  Defaults: computer_screenshot
  Specifies the event type. For a computer screenshot, this property is always set to computer_screenshot.
  computer_screenshot
  string
  image_url
  string
  The URL of the screenshot image.
  file_id
  string
  The identifier of an uploaded file that contains the screenshot.
  acknowledged_safety_checks
  array or null
  acknowledged_safety_checks
  array
  The safety checks reported by the API that have been acknowledged by the developer.
  items
  object
  A pending safety check for the computer call.
  id
  string
  Required
  The ID of the pending safety check.
  code
  string or null
  code
  string
  The type of the pending safety check.
  code
  null
  message
  string or null
  message
  string
  Details about the pending safety check.
  message
  null
  acknowledged_safety_checks
  null
  status
  string or null
  status
  string
  The status of the message input. One of in_progress, completed, or incomplete. Populated when input items are returned via API.
  in_progress
  string
  completed
  string
  incomplete
  string
  status
  null
  Web search tool call
  object
  The results of a web search tool call. See the web search guide for more information.
  id
  string
  Required
  The unique ID of the web search tool call.
  type
  string
  Required
  The type of the web search tool call. Always web_search_call.
  web_search_call
  string
  status
  string
  Required
  The status of the web search tool call.
  in_progress
  string
  searching
  string
  completed
  string
  failed
  string
  Function tool call
  object
  A tool call to run a function. See the function calling guide for more information.
  id
  string
  The unique ID of the function tool call.
  type
  string
  Required
  The type of the function tool call. Always function_call.
  function_call
  string
  call_id
  string
  Required
  The unique ID of the function tool call generated by the model.
  name
  string
  Required
  The name of the function to run.
  arguments
  string
  Required
  A JSON string of the arguments to pass to the function.
  status
  string
  The status of the item. One of in_progress, completed, or incomplete. Populated when items are returned via API.
  in_progress
  string
  completed
  string
  incomplete
  string
  Function tool call output
  object
  The output of a function tool call.
  id
  string or null
  id
  string
  The unique ID of the function tool call output. Populated when this item is returned via API.
  id
  null
  call_id
  string
  Required
  The unique ID of the function tool call generated by the model.
  type
  string
  Required
  Defaults: function_call_output
  The type of the function tool call output. Always function_call_output.
  function_call_output
  string
  output
  string
  Required
  A JSON string of the output of the function tool call.
  status
  string or null
  status
  string
  The status of the item. One of in_progress, completed, or incomplete. Populated when items are returned via API.
  in_progress
  string
  completed
  string
  incomplete
  string
  status
  null
  Reasoning
  object
  A description of the chain of thought used by a reasoning model while generating a response.
  type
  string
  Required
  The type of the object. Always reasoning.
  reasoning
  string
  id
  string
  Required
  The unique identifier of the reasoning content.
  summary
  array
  Required
  Reasoning text contents.
  items
  object
  type
  string
  Required
  The type of the object. Always summary_text.
  summary_text
  string
  text
  string
  Required
  A short summary of the reasoning used by the model when generating the response.
  status
  string
  The status of the item. One of in_progress, completed, or incomplete. Populated when items are returned via API.
  in_progress
  string
  completed
  string
  incomplete
  string
  Item reference
  object
  An internal identifier for an item to reference.
  type
  string or null
  type
  string
  Defaults: item_reference
  The type of item to reference. Always item_reference.
  item_reference
  string
  type
  null
  id
  string
  Required
  The ID of the item to reference.
include
array or null
Specify additional output data to include in the model response. Currently supported values are:
- file_search_call.results: Include the search results of the file search tool call.
- message.input_image.image_url: Include image urls from the input message.
- computer_call_output.output.image_url: Include image urls from the computer call output.
- items
  string
  Specify additional output data to include in the model response. Currently supported values are:
  file_search_call.results: Include the search results of the file search tool call.
  message.input_image.image_url: Include image urls from the input message.
  computer_call_output.output.image_url: Include image urls from the computer call output.
  file_search_call.results
  string
  message.input_image.image_url
  string
  computer_call_output.output.image_url
  string
parallel_tool_calls
boolean or null
Defaults: true
Whether to allow the model to run tool calls in parallel.
store
boolean or null
Defaults: true
Whether to store the generated model response for later retrieval via API.
stream
boolean or null
Defaults: false
If set to true, the model response data will be streamed to the client as it is generated using server-sent events. See the Streaming section below for more information.

Response

Returns a Response object.

Example request

1curl https://api.openai.com/v1/responses \
2  -H "Content-Type: application/json" \
3  -H "Authorization: Bearer $OPENAI_API_KEY" \
4  -d '{
5    "model": "gpt-4.1",
6    "input": "Tell me a three sentence bedtime story about a unicorn."
7  }'

Example response

1{
2  "id": "resp_67ccd2bed1ec8190b14f964abc0542670bb6a6b452d3795b",
3  "object": "response",
4  "created_at": 1741476542,
5  "status": "completed",
6  "error": null,
7  "incomplete_details": null,
8  "instructions": null,
9  "max_output_tokens": null,
10  "model": "gpt-4.1-2025-04-14",
11  "output": [
12    {
13      "type": "message",
14      "id": "msg_67ccd2bf17f0819081ff3bb2cf6508e60bb6a6b452d3795b",
15      "status": "completed",
16      "role": "assistant",
17      "content": [
18        {
19          "type": "output_text",
20          "text": "In a peaceful grove beneath a silver moon, a unicorn named Lumina discovered a hidden pool that reflected the stars. As she dipped her horn into the water, the pool began to shimmer, revealing a pathway to a magical realm of endless night skies. Filled with wonder, Lumina whispered a wish for all who dream to find their own hidden magic, and as she glanced back, her hoofprints sparkled like stardust.",
21          "annotations": []
22        }
23      ]
24    }
25  ],
26  "parallel_tool_calls": true,
27  "previous_response_id": null,
28  "reasoning": {
29    "effort": null,
30    "summary": null
31  },
32  "store": true,
33  "temperature": 1.0,
34  "text": {
35    "format": {
36      "type": "text"
37    }
38  },
39  "tool_choice": "auto",
40  "tools": [],
41  "top_p": 1.0,
42  "truncation": "disabled",
43  "usage": {
44    "input_tokens": 36,
45    "input_tokens_details": {
46      "cached_tokens": 0
47    },
48    "output_tokens": 87,
49    "output_tokens_details": {
50      "reasoning_tokens": 0
51    },
52    "total_tokens": 123
53  },
54  "user": null,
55  "metadata": {}
56}

Built with