Create response

curl --request POST \
  --url https://api.openai.com/v1/responses \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "<string>",
  "input": "<string>",
  "include": [
    "reasoning.encrypted_content"
  ],
  "tools": [
    {
      "name": "<string>",
      "type": "function",
      "description": "<string>",
      "parameters": {},
      "strict": true
    }
  ],
  "tool_choice": {
    "type": "function",
    "name": "<string>"
  },
  "metadata": {},
  "text": {
    "format": {
      "type": "text"
    },
    "verbosity": "low"
  },
  "temperature": 123,
  "top_p": 123,
  "presence_penalty": 123,
  "frequency_penalty": 123,
  "parallel_tool_calls": true,
  "stream": true,
  "stream_options": {
    "include_obfuscation": true
  },
  "background": true,
  "max_output_tokens": 17,
  "max_tool_calls": 2,
  "reasoning": {
    "effort": "none",
    "summary": "concise"
  },
  "safety_identifier": "<string>",
  "prompt_cache_key": "<string>",
  "truncation": "auto",
  "instructions": "<string>",
  "store": true,
  "service_tier": "auto",
  "top_logprobs": 10
}
'

{
  "id": "resp_67ccd3a9da748190baa7f1570fe91ac604becb25c45c1d41",
  "object": "response",
  "created_at": 1741476777,
  "status": "completed",
  "completed_at": 1741476778,
  "model": "gpt-4o-2024-08-06",
  "output": [
    {
      "type": "message",
      "id": "msg_67ccd3acc8d48190a77525dc6de64b4104becb25c45c1d41",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "The image depicts a scenic landscape with a wooden boardwalk or pathway leading through lush, green grass under a blue sky with some clouds. The setting suggests a peaceful natural area, possibly a park or nature reserve. There are trees and shrubs in the background.",
          "annotations": []
        }
      ]
    }
  ],
  "parallel_tool_calls": true,
  "reasoning": {},
  "store": true,
  "background": false,
  "temperature": 1,
  "presence_penalty": 0,
  "frequency_penalty": 0,
  "text": {
    "format": {
      "type": "text"
    }
  },
  "tool_choice": "auto",
  "tools": [],
  "top_p": 1,
  "truncation": "disabled",
  "usage": {
    "input_tokens": 328,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 52,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 380
  },
  "metadata": {}
}

POST

responses

Create response

curl --request POST \
  --url https://api.openai.com/v1/responses \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "<string>",
  "input": "<string>",
  "include": [
    "reasoning.encrypted_content"
  ],
  "tools": [
    {
      "name": "<string>",
      "type": "function",
      "description": "<string>",
      "parameters": {},
      "strict": true
    }
  ],
  "tool_choice": {
    "type": "function",
    "name": "<string>"
  },
  "metadata": {},
  "text": {
    "format": {
      "type": "text"
    },
    "verbosity": "low"
  },
  "temperature": 123,
  "top_p": 123,
  "presence_penalty": 123,
  "frequency_penalty": 123,
  "parallel_tool_calls": true,
  "stream": true,
  "stream_options": {
    "include_obfuscation": true
  },
  "background": true,
  "max_output_tokens": 17,
  "max_tool_calls": 2,
  "reasoning": {
    "effort": "none",
    "summary": "concise"
  },
  "safety_identifier": "<string>",
  "prompt_cache_key": "<string>",
  "truncation": "auto",
  "instructions": "<string>",
  "store": true,
  "service_tier": "auto",
  "top_logprobs": 10
}
'

{
  "id": "resp_67ccd3a9da748190baa7f1570fe91ac604becb25c45c1d41",
  "object": "response",
  "created_at": 1741476777,
  "status": "completed",
  "completed_at": 1741476778,
  "model": "gpt-4o-2024-08-06",
  "output": [
    {
      "type": "message",
      "id": "msg_67ccd3acc8d48190a77525dc6de64b4104becb25c45c1d41",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "The image depicts a scenic landscape with a wooden boardwalk or pathway leading through lush, green grass under a blue sky with some clouds. The setting suggests a peaceful natural area, possibly a park or nature reserve. There are trees and shrubs in the background.",
          "annotations": []
        }
      ]
    }
  ],
  "parallel_tool_calls": true,
  "reasoning": {},
  "store": true,
  "background": false,
  "temperature": 1,
  "presence_penalty": 0,
  "frequency_penalty": 0,
  "text": {
    "format": {
      "type": "text"
    }
  },
  "tool_choice": "auto",
  "tools": [],
  "top_p": 1,
  "truncation": "disabled",
  "usage": {
    "input_tokens": 328,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 52,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 380
  },
  "metadata": {}
}

Body

model

string

The model to use for this request. We follow the HuggingFace name style, e.g. 'deepseek-ai/DeepSeek-V3.2'.

input

Context to provide to the model for the scope of this request. May either be a string or an array of input items. If a string is provided, it is interpreted as a user message.

Maximum string length: 10485760

include

enum<string>[]

Available options:

reasoning.encrypted_content,

message.output_text.logprobs

tools

object[] | null

A list of tools that the model may call while generating the response.

Show child attributes

tool_choice

Controls which tool the model should use, if any.

Show child attributes

metadata

object

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.

Show child attributes

text

object

Configuration options for text output.

Show child attributes

temperature

number | null

Sampling temperature to use, between 0 and 2. Higher values make the output more random.

top_p

number | null

Nucleus sampling parameter, between 0 and 1. The model considers only the tokens with the top cumulative probability.

presence_penalty

number | null

Penalizes new tokens based on whether they appear in the text so far.

frequency_penalty

number | null

Penalizes new tokens based on their frequency in the text so far.

parallel_tool_calls

boolean | null

Whether the model may call multiple tools in parallel.

stream

boolean

Whether to stream response events as server-sent events.

stream_options

object

Options that control streamed response behavior.

Show child attributes

background

boolean

Whether to run the request in the background and return immediately.

max_output_tokens

integer | null

The maximum number of tokens the model may generate for this response.

Required range: x >= 16

max_tool_calls

integer | null

The maximum number of tool calls the model may make while generating the response.

Required range: x >= 1

reasoning

object

Configuration options for reasoning behavior.

Show child attributes

safety_identifier

string | null

A stable identifier used for safety monitoring and abuse detection.

Maximum string length: 64

prompt_cache_key

string | null

A key to use when reading from or writing to the prompt cache.

Maximum string length: 64

truncation

enum<string>

Controls how the service truncates the input when it exceeds the model context window.

Available options:

auto,

disabled

instructions

string | null

Additional instructions to guide the model for this request.

store

boolean

Whether to store the response so it can be retrieved later.

service_tier

enum<string>

The service tier to use for this request.

Available options:

auto,

default,

flex,

priority

top_logprobs

integer | null

The number of most likely tokens to return at each position, along with their log probabilities.

Required range: 0 <= x <= 20

Response

Success

The complete response object that was returned by the Responses API.

string

required

The unique ID of the response that was created.

object

enum<string>

default:response

required

The object type, which was always response.

Available options:

response

created_at

integer

required

The Unix timestamp (in seconds) for when the response was created.

completed_at

integer | null

required

The Unix timestamp (in seconds) for when the response was completed, if it was completed.

status

string

required

The status that was set for the response.

incomplete_details

Incomplete details · object

required

Details about why the response was incomplete, if applicable.

Show child attributes

model

string

required

The model that generated this response.

previous_response_id

string | null

required

The ID of the previous response in the chain that was referenced, if any.

instructions

string | null

required

Additional instructions that were used to guide the model for this response.

output

(Message · object | Function call · object | Function call output · object | Reasoning item · object)[]

required

The output items that were generated by the model.

An item representing a message, tool call, tool output, reasoning, or other response element.

Message
Function call
Function call output
Reasoning item

Show child attributes

error

Error · object

required

The error that occurred, if the response failed.

Show child attributes

tools

Function · object[]

required

The tools that were available to the model during response generation.

Show child attributes

tool_choice

required

Show child attributes

truncation

enum<string>

required

How the input was truncated by the service when it exceeded the model context window.

Available options:

auto,

disabled

parallel_tool_calls

boolean

required

Whether the model was allowed to call multiple tools in parallel.

text

object

required

Configuration options for text output that were used.

Show child attributes

top_p

number

required

The nucleus sampling parameter that was used for this response.

presence_penalty

number

required

The presence penalty that was used to penalize new tokens based on whether they appear in the text so far.

frequency_penalty

number

required

The frequency penalty that was used to penalize new tokens based on their frequency in the text so far.

top_logprobs

integer

required

The number of most likely tokens that were returned at each position, along with their log probabilities.

temperature

number

required

The sampling temperature that was used for this response.

reasoning

Reasoning · object

required

Reasoning configuration and outputs that were produced for this response.

Show child attributes

usage

Usage · object

required

Token usage statistics that were recorded for the response, if available.

Show child attributes

max_output_tokens

integer | null

required

The maximum number of tokens the model was allowed to generate for this response.

max_tool_calls

integer | null

required

The maximum number of tool calls the model was allowed to make while generating the response.

store

boolean

required

Whether this response was stored so it can be retrieved later.

background

boolean

required

Whether this request was run in the background.

service_tier

string

required

The service tier that was used for this response.

metadata

any

required

Developer-defined metadata that was associated with the response.

safety_identifier

string | null

required

A stable identifier that was used for safety monitoring and abuse detection.

prompt_cache_key

string | null

required

A key that was used to read from or write to the prompt cache.

Get a model response

⌘I

API Reference

Body

Response