v1

latestOpenAPI 3.1.02026-07-2611077199.5 KB

Create a model response

Creates a model response from text, image, or file input. Supports structured output, tool calls, conversation state, background processing, and streaming.

post/v1/responses

Request body

modelstring

Model ID used to generate the response. See Supported Models.

instructionsstring

A system or developer message inserted into the model context. It is not carried over when previous_response_id is used.

previous_response_idstring

ID of the previous response for multi-turn interactions. Cannot be used together with conversation.

backgroundboolean

Whether to run the response in the background.

includestring[]

Additional output data to include in the response.

max_output_tokensinteger

Maximum number of generated tokens, including visible output and reasoning tokens.

max_tool_callsinteger

Maximum total number of built-in tool calls processed for this response.

metadataobject

Up to 16 string key-value pairs attached to the response.

parallel_tool_callsboolean

Whether the model may call tools in parallel.

prompt_cache_keystring

Stable key used to improve prompt cache hit rates.

prompt_cache_retention'in-memory' | '24h'

Prompt cache retention policy.

safety_identifierstring

Stable identifier for the end user, used for abuse detection.

service_tier'auto' | 'default' | 'flex' | 'scale' | 'priority'

storeboolean

Whether to store the generated response for later retrieval.

streamboolean

Whether to stream response events using server-sent events.

temperaturenumber

Sampling temperature. Change this or top_p, but generally not both.

toolsobject[]

Tools available to the model, including function and supported built-in tools.

top_logprobsinteger

top_pnumber

truncation'auto' | 'disabled'

Example request

{
  "model": "gpt-5.4-mini",
  "input": "Explain quantum computing in simple terms."
}

Response

Successful response. When stream is true, the endpoint returns server-sent events.

idstring required

object'response' required

created_atnumber required

modelstring required

output_textstring

SDK convenience property containing aggregated text output.

previous_response_idstring nullable

storeboolean

metadataobject

Example response

{
  "id": "resp_67ccd2bed1ec8190b14f964abc0542670bb6a6b452d3795b",
  "created_at": 1741476542
}