OpenAI Response Format (Responses)¶
Official Documentation
📝 Introduction¶
OpenAI's most advanced model response interface. Supports text and image input, as well as text output. Creates stateful interactions with models, using previous response outputs as input. Extends model capabilities through built-in tools such as file search, web search, computer usage, etc. Uses function calling to allow models to access external systems and data.
For related guidelines, please refer to the OpenAI official website: Responses
💡 Request Examples¶
Basic Text Response ✅¶
curl https://your-newapi-server-address/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $NEWAPI_API_KEY" \
-d '{
"model": "gpt-4.1",
"input": "Tell a three-sentence bedtime story about a unicorn."
}'
Response Example:
{
"id": "resp_67ccd2bed1ec8190b14f964abc0542670bb6a6b452d3795b",
"object": "response",
"created_at": 1741476542,
"status": "completed",
"error": null,
"incomplete_details": null,
"instructions": null,
"max_output_tokens": null,
"model": "gpt-4.1",
"output": [
{
"type": "message",
"id": "msg_67ccd2bf17f0819081ff3bb2cf6508e60bb6a6b452d3795b",
"status": "completed",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "On a peaceful moonlit night, a unicorn named Lumina discovered a hidden pool reflecting the stars. When she dipped her horn into the water, the pool began to shimmer, revealing a path to a magical world with endless night skies. Filled with wonder, Lumina made a wish for all dreamers to find their own hidden magic, and as she looked back, her hoofprints sparkled like stardust.",
"annotations": []
}
]
}
],
"parallel_tool_calls": true,
"previous_response_id": null,
"reasoning": {
"effort": null,
"summary": null
},
"store": true,
"temperature": 1.0,
"text": {
"format": {
"type": "text"
}
},
"tool_choice": "auto",
"tools": [],
"top_p": 1.0,
"truncation": "disabled",
"usage": {
"input_tokens": 36,
"input_tokens_details": {
"cached_tokens": 0
},
"output_tokens": 87,
"output_tokens_details": {
"reasoning_tokens": 0
},
"total_tokens": 123
},
"user": null,
"metadata": {}
}
Image Analysis Response ✅¶
curl https://your-newapi-server-address/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $NEWAPI_API_KEY" \
-d '{
"model": "gpt-4.1",
"input": [
{
"role": "user",
"content": [
{"type": "input_text", "text": "Describe what's in this image"},
{
"type": "input_image",
"image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"
}
]
}
]
}'
Response Example:
{
"id": "resp_67ccd3a9da748190baa7f1570fe91ac604becb25c45c1d41",
"object": "response",
"created_at": 1741476777,
"status": "completed",
"error": null,
"incomplete_details": null,
"instructions": null,
"max_output_tokens": null,
"model": "gpt-4.1",
"output": [
{
"type": "message",
"id": "msg_67ccd3acc8d48190a77525dc6de64b4104becb25c45c1d41",
"status": "completed",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "This image shows a wooden boardwalk or path through dense green grass, with a blue sky dotted with a few clouds above. The scene presents a peaceful natural area, possibly a park or nature reserve. There are trees and shrubs in the background. The entire landscape showcases a harmonious natural environment, with the boardwalk providing visitors a path through wetlands or grasslands without affecting the surrounding ecosystem.",
"annotations": []
}
]
}
],
"parallel_tool_calls": true,
"previous_response_id": null,
"reasoning": {
"effort": null,
"summary": null
},
"store": true,
"temperature": 1.0,
"text": {
"format": {
"type": "text"
}
},
"tool_choice": "auto",
"tools": [],
"top_p": 1.0,
"truncation": "disabled",
"usage": {
"input_tokens": 328,
"input_tokens_details": {
"cached_tokens": 0
},
"output_tokens": 52,
"output_tokens_details": {
"reasoning_tokens": 0
},
"total_tokens": 380
},
"user": null,
"metadata": {}
}
Web Search Tool ✅¶
curl https://your-newapi-server-address/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $NEWAPI_API_KEY" \
-d '{
"model": "gpt-4.1",
"tools": [{ "type": "web_search_preview" }],
"input": "What are some positive news stories today?"
}'
Response Example:
{
"id": "resp_67ccf18ef5fc8190b16dbee19bc54e5f087bb177ab789d5c",
"object": "response",
"created_at": 1741484430,
"status": "completed",
"error": null,
"incomplete_details": null,
"instructions": null,
"max_output_tokens": null,
"model": "gpt-4.1",
"output": [
{
"type": "web_search_call",
"id": "ws_67ccf18f64008190a39b619f4c8455ef087bb177ab789d5c",
"status": "completed"
},
{
"type": "message",
"id": "msg_67ccf190ca3881909d433c50b1f6357e087bb177ab789d5c",
"status": "completed",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "As of today, March 9, 2025, a noteworthy positive news story is China's breakthrough in renewable energy, successfully developing a new type of highly efficient solar cell with a record conversion efficiency of 35%, which could significantly drive the adoption and application of clean energy. This technology is expected to reduce solar power costs by about 40%, providing a new solution for global carbon emission reduction. This technology is expected to reduce solar power costs by about 40%, providing a new solution for global carbon emission reduction.",
"annotations": [
{
"type": "url_citation",
"start_index": 42,
"end_index": 100,
"url": "https://example.com/renewable-energy-breakthrough/?utm_source=chatgpt.com",
"title": "China's breakthrough in renewable energy"
},
{
"type": "url_citation",
"start_index": 101,
"end_index": 150,
"url": "https://example.com/solar-cell-efficiency-record/?utm_source=chatgpt.com",
"title": "New highly efficient solar cell conversion efficiency record"
},
{
"type": "url_citation",
"start_index": 151,
"end_index": 200,
"url": "https://example.com/clean-energy-cost-reduction/?utm_source=chatgpt.com",
"title": "Solar power costs expected to decrease by 40%"
}
]
}
]
}
],
"parallel_tool_calls": true,
"previous_response_id": null,
"reasoning": {
"effort": null,
"summary": null
},
"store": true,
"temperature": 1.0,
"text": {
"format": {
"type": "text"
}
},
"tool_choice": "auto",
"tools": [
{
"type": "web_search_preview",
"domains": [],
"search_context_size": "medium",
"user_location": {
"type": "approximate",
"city": null,
"country": "US",
"region": null,
"timezone": null
}
}
],
"top_p": 1.0,
"truncation": "disabled",
"usage": {
"input_tokens": 328,
"input_tokens_details": {
"cached_tokens": 0
},
"output_tokens": 356,
"output_tokens_details": {
"reasoning_tokens": 0
},
"total_tokens": 684
},
"user": null,
"metadata": {}
}
File Search Tool ✅¶
curl https://your-newapi-server-address/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $NEWAPI_API_KEY" \
-d '{
"model": "gpt-4.1",
"tools": [{
"type": "file_search",
"vector_store_ids": ["vs_1234567890"],
"max_num_results": 20
}],
"input": "What are the characteristics and properties of ancient brown dragons?"
}'
Response Example:
{
"id": "resp_67ccf4c55fc48190b71bd0463ad3306d09504fb6872380d7",
"object": "response",
"created_at": 1741485253,
"status": "completed",
"error": null,
"incomplete_details": null,
"instructions": null,
"max_output_tokens": null,
"model": "gpt-4.1",
"output": [
{
"type": "file_search_call",
"id": "fs_67ccf4c63cd08190887ef6464ba5681609504fb6872380d7",
"status": "completed",
"queries": [
"What are the characteristics and properties of ancient brown dragons?"
],
"results": null
},
{
"type": "message",
"id": "msg_67ccf4c93e5c81909d595b369351a9d309504fb6872380d7",
"status": "completed",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "According to the materials, ancient brown dragons have the following characteristics and properties:\n\n1. Physical characteristics: Ancient brown dragons are massive, with a body length of 25-30 meters and a wingspan of about 35 meters. Their scales are dark brown to copper, becoming darker with age. They have characteristic double horns and spine spikes on their heads, strong jaws suitable for tearing prey. They also have excellent burrowing abilities, often digging complex nest systems in deserts or mountains.\n\n2. Abilities: They can spit powerful acid, causing severe corrosion damage to targets. Ancient brown dragons also have excellent burrowing abilities, often digging complex nest systems in deserts or mountains. Ancient brown dragons also have excellent burrowing abilities, often digging complex nest systems in deserts or mountains.\n\n3. Intelligence: Considered the most cunning and patient breed among dragon species, with extremely high intelligence, proficient in multiple languages, and possessing complex tactical thinking.\n\n4. Habitat: Primarily found in arid mountainous and desert regions, preferring hot and dry environments.\n\n5. Treasures: Ancient brown dragons are renowned for their vast treasures, particularly for collecting copper coins, rubies, and flame magic items.\n\n6. Lifespan: One of the longest among all dragon breeds, with a lifespan of 2000-2500 years, and its strength and magical abilities also increase with age.\n\n7. Personality: Extremely territorial, aggressive, and merciless to intruders, but also renowned for its rare patience, capable of waiting for centuries for revenge.",
"annotations": [
{
"type": "file_citation",
"index": 80,
"file_id": "file-4wDz5b167pAf72nx1h9eiN",
"filename": "dragons.pdf"
},
{
"type": "file_citation",
"index": 233,
"file_id": "file-4wDz5b167pAf72nx1h9eiN",
"filename": "dragons.pdf"
},
{
"type": "file_citation",
"index": 345,
"file_id": "file-4wDz5b167pAf72nx1h9eiN",
"filename": "dragons.pdf"
},
{
"type": "file_citation",
"index": 420,
"file_id": "file-4wDz5b167pAf72nx1h9eiN",
"filename": "dragons.pdf"
},
{
"type": "file_citation",
"index": 520,
"file_id": "file-4wDz5b167pAf72nx1h9eiN",
"filename": "dragons.pdf"
},
{
"type": "file_citation",
"index": 580,
"file_id": "file-4wDz5b167pAf72nx1h9eiN",
"filename": "dragons.pdf"
},
{
"type": "file_citation",
"index": 655,
"file_id": "file-4wDz5b167pAf72nx1h9eiN",
"filename": "dragons.pdf"
},
{
"type": "file_citation",
"index": 781,
"file_id": "file-4wDz5b167pAf72nx1h9eiN",
"filename": "dragons.pdf"
}
]
}
]
}
],
"parallel_tool_calls": true,
"previous_response_id": null,
"reasoning": {
"effort": null,
"summary": null
},
"store": true,
"temperature": 1.0,
"text": {
"format": {
"type": "text"
}
},
"tool_choice": "auto",
"tools": [
{
"type": "file_search",
"filters": null,
"max_num_results": 20,
"ranking_options": {
"ranker": "auto",
"score_threshold": 0.0
},
"vector_store_ids": [
"vs_1234567890"
]
}
],
"top_p": 1.0,
"truncation": "disabled",
"usage": {
"input_tokens": 18307,
"input_tokens_details": {
"cached_tokens": 0
},
"output_tokens": 348,
"output_tokens_details": {
"reasoning_tokens": 0
},
"total_tokens": 18655
},
"user": null,
"metadata": {}
}
Streaming Response ✅¶
curl https://your-newapi-server-address/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $NEWAPI_API_KEY" \
-d '{
"model": "gpt-4.1",
"instructions": "You are a helpful assistant.",
"input": "Hello!",
"stream": true
}'
Streaming Response Example:
event: response.created
data: {"type":"response.created","response":{"id":"resp_67c9fdcecf488190bdd9a0409de3a1ec07b8b0ad4e5eb654","object":"response","created_at":1741290958,"status":"in_progress","error":null,"incomplete_details":null,"instructions":"You are a helpful assistant.","max_output_tokens":null,"model":"gpt-4.1-2025-04-14","output":[],"parallel_tool_calls":true,"previous_response_id":null,"reasoning":{"effort":null,"summary":null},"store":true,"temperature":1.0,"text":{"format":{"type":"text"}},"tool_choice":"auto","tools":[],"top_p":1.0,"truncation":"disabled","usage":null,"user":null,"metadata":{}}}
event: response.in_progress
data: {"type":"response.in_progress","response":{"id":"resp_67c9fdcecf488190bdd9a0409de3a1ec07b8b0ad4e5eb654","object":"response","created_at":1741290958,"status":"in_progress","error":null,"incomplete_details":null,"instructions":"You are a helpful assistant.","max_output_tokens":null,"model":"gpt-4.1-2025-04-14","output":[],"parallel_tool_calls":true,"previous_response_id":null,"reasoning":{"effort":null,"summary":null},"store":true,"temperature":1.0,"text":{"format":{"type":"text"}},"tool_choice":"auto","tools":[],"top_p":1.0,"truncation":"disabled","usage":null,"user":null,"metadata":{}}}
event: response.output_item.added
data: {"type":"response.output_item.added","output_index":0,"item":{"id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","type":"message","status":"in_progress","role":"assistant","content":[]}}
event: response.content_part.added
data: {"type":"response.content_part.added","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"part":{"type":"output_text","text":"","annotations":[]}}
event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"Hello"}
event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"!"}
event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":" I"}
event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"can"}
event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"provide"}
event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"what"}
event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"help"}
event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"?"}
event: response.output_text.done
data: {"type":"response.output_text.done","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"text":"Hello! What can I help you with?"}
event: response.content_part.done
data: {"type":"response.content_part.done","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"part":{"type":"output_text","text":"Hello! What can I help you with?","annotations":[]}}
event: response.output_item.done
data: {"type":"response.output_item.done","output_index":0,"item":{"id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","type":"message","status":"completed","role":"assistant","content":[{"type":"output_text","text":"Hello! What can I help you with?","annotations":[]}]}}
event: response.completed
data: {"type":"response.completed","response":{"id":"resp_67c9fdcecf488190bdd9a0409de3a1ec07b8b0ad4e5eb654","object":"response","created_at":1741290958,"status":"completed","error":null,"incomplete_details":null,"instructions":"You are a helpful assistant.","max_output_tokens":null,"model":"gpt-4.1-2025-04-14","output":[{"id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","type":"message","status":"completed","role":"assistant","content":[{"type":"output_text","text":"Hello! What can I help you with?","annotations":[]}]}],"parallel_tool_calls":true,"previous_response_id":null,"reasoning":{"effort":null,"summary":null},"store":true,"temperature":1.0,"text":{"format":{"type":"text"}},"tool_choice":"auto","tools":[],"top_p":1.0,"truncation":"disabled","usage":{"input_tokens":37,"output_tokens":11,"output_tokens_details":{"reasoning_tokens":0},"total_tokens":48},"user":null,"metadata":{}}}
Function Calling ✅¶
curl https://your-newapi-server-address/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $NEWAPI_API_KEY" \
-d '{
"model": "gpt-4.1",
"input": "What is the weather in Boston today?",
"tools": [
{
"type": "function",
"name": "get_current_weather",
"description": "Get the current weather for a specified location",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "City and state, e.g., San Francisco, CA"
},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"]
}
},
"required": ["location", "unit"]
}
}
],
"tool_choice": "auto"
}'
Response Example:
{
"id": "resp_67ca09c5efe0819096d0511c92b8c890096610f474011cc0",
"object": "response",
"created_at": 1741294021,
"status": "completed",
"error": null,
"incomplete_details": null,
"instructions": null,
"max_output_tokens": null,
"model": "gpt-4.1-2025-04-14",
"output": [
{
"type": "function_call",
"id": "fc_67ca09c6bedc8190a7abfec07b1a1332096610f474011cc0",
"call_id": "call_unLAR8MvFNptuiZK6K6HCy5k",
"name": "get_current_weather",
"arguments": "{\"location\":\"Boston, MA\",\"unit\":\"celsius\"}",
"status": "completed"
}
],
"parallel_tool_calls": true,
"previous_response_id": null,
"reasoning": {
"effort": null,
"summary": null
},
"store": true,
"temperature": 1.0,
"text": {
"format": {
"type": "text"
}
},
"tool_choice": "auto",
"tools": [
{
"type": "function",
"description": "Get the current weather for a specified location",
"name": "get_current_weather",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "City and state, e.g., San Francisco, CA"
},
"unit": {
"type": "string",
"enum": [
"celsius",
"fahrenheit"
]
}
},
"required": [
"location",
"unit"
]
},
"strict": true
}
],
"top_p": 1.0,
"truncation": "disabled",
"usage": {
"input_tokens": 291,
"output_tokens": 23,
"output_tokens_details": {
"reasoning_tokens": 0
},
"total_tokens": 314
},
"user": null,
"metadata": {}
}
Reasoning Ability ✅¶
curl https://your-newapi-server-address/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $NEWAPI_API_KEY" \
-d '{
"model": "o3-mini",
"input": "How many woodpeckers can peck wood?",
"reasoning": {
"effort": "high"
}
}'
Response Example:
{
"id": "resp_67ccd7eca01881908ff0b5146584e408072912b2993db808",
"object": "response",
"created_at": 1741477868,
"status": "completed",
"error": null,
"incomplete_details": null,
"instructions": null,
"max_output_tokens": null,
"model": "o1-2024-12-17",
"output": [
{
"type": "message",
"id": "msg_67ccd7f7b5848190a6f3e95d809f6b44072912b2993db808",
"status": "completed",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "This is a quote from the English tongue twister \"How much wood would a woodchuck chuck if a woodchuck could chuck wood\". In reality, woodpeckers (woodpecker) and woodchucks (woodchuck) are different animals, and woodchucks do not \"chuck\" wood. \n\nFrom a scientific perspective, woodpeckers do indeed peck trees every day to find food, build nests, or communicate. On average, a woodpecker might peck a tree about 8000-12000 times per day, depending on the species and specific purpose. If we convert this to wood volume, assuming each peck removes about 0.1-0.2 cubic centimeters of wood, then a woodpecker theoretically might remove about 800-2400 cubic centimeters of wood per day. \n\nHowever, woodpeckers are primarily foraging and nesting, not just removing wood, so this calculation is just an interesting theoretical estimate.",
"annotations": []
}
]
}
],
"parallel_tool_calls": true,
"previous_response_id": null,
"reasoning": {
"effort": "high",
"summary": null
},
"store": true,
"temperature": 1.0,
"text": {
"format": {
"type": "text"
}
},
"tool_choice": "auto",
"tools": [],
"top_p": 1.0,
"truncation": "disabled",
"usage": {
"input_tokens": 81,
"input_tokens_details": {
"cached_tokens": 0
},
"output_tokens": 1035,
"output_tokens_details": {
"reasoning_tokens": 832
},
"total_tokens": 1116
},
"user": null,
"metadata": {}
}
📮 Request¶
Endpoint¶
Create a model response. Provide text or image input to generate text or JSON output. Let the model call your own custom code or use built-in tools (such as web search or file search) to use your own data as input for the model response.
Authentication Method¶
Include the following in the request header for API key authentication:
Where $NEWAPI_API_KEY
is your API key.
Request Body Parameters¶
input¶
Type: String or Array
Required: Yes
The text, image, or file input provided to the model to generate a response.
Possible Types¶
Type | Description |
---|---|
String | Text input, equivalent to text input with user role |
Input item array | A list of one or more input items of different content types |
Input Message Object¶
Property | Type | Required | Description |
---|---|---|---|
content | String or Array | Yes | The text, image, or audio input provided to the model to generate a response. It can also include previous assistant responses |
role | String | Yes | The role of the input message. Optional values: user , assistant , system , or developer |
type | String | No | The type of the input message, always message |
Content Item Types¶
Text Input¶
Property | Type | Required | Description |
---|---|---|---|
text | String | Yes | The text input provided to the model |
type | String | Yes | The type of the input item, always input_text |
Image Input¶
Property | Type | Required | Description |
---|---|---|---|
detail | String | Yes | The detailed level of the image to send to the model. Optional values: high , low , or auto . Default is auto |
type | String | Yes | The type of the input item, always input_image |
file_id | String | No | The file ID to send to the model |
image_url | String | No | The image URL to send to the model. It can be a full URL or base64 encoded image in a data URL |
File Input¶
Property | Type | Required | Description |
---|---|---|---|
type | String | Yes | The type of the input item, always input_file |
file_data | String | No | The content of the file to send to the model |
file_id | String | No | The file ID to send to the model |
filename | String | No | The filename to send to the model |
Output Item Types¶
Output Text¶
Property | Type | Required | Description |
---|---|---|---|
text | String | Yes | The text output generated by the model |
type | String | Yes | The type of the output item, always output_text |
annotations | Array | Yes | Annotations for the text output |
Annotation Types¶
File Reference:
Property | Type | Required | Description |
---|---|---|---|
file_id | String | Yes | The ID of the file |
index | Integer | Yes | The index of the file in the file list |
type | String | Yes | The type of file reference, always file_citation |
URL Reference:
Property | Type | Required | Description |
---|---|---|---|
end_index | Integer | Yes | The index of the last character of the URL reference in the message |
start_index | Integer | Yes | The index of the first character of the URL reference in the message |
title | String | Yes | The title of the network resource |
type | String | Yes | The type of URL reference, always url_citation |
url | String | Yes | The URL of the network resource |
File Path:
Property | Type | Required | Description |
---|---|---|---|
file_id | String | Yes | The ID of the file |
index | Integer | Yes | The index of the file in the file list |
type | String | Yes | The type of file path, always file_path |
Rejected Response¶
Property | Type | Required | Description |
---|---|---|---|
refusal | String | Yes | The model's refusal explanation |
type | String | Yes | The type of refusal, always refusal |
Tool Call Types¶
File Search Tool Call¶
Property | Type | Required | Description |
---|---|---|---|
id | String | Yes | The unique ID of the file search tool call |
queries | Array | Yes | The queries for searching files |
status | String | Yes | The status of the file search tool call. Possible values include: in_progress , searching , incomplete , or failed |
type | String | Yes | The type of the file search tool call, always file_search_call |
results | Array or null | No | The results of the file search tool call |
Web Search Tool Call¶
Property | Type | Required | Description |
---|---|---|---|
id | String | Yes | The unique ID of the web search tool call |
status | String | Yes | The status of the web search tool call |
type | String | Yes | The type of the web search tool call, always web_search_call |
Function Tool Call¶
Property | Type | Required | Description |
---|---|---|---|
arguments | String | Yes | The JSON string of parameters passed to the function |
call_id | String | Yes | The unique ID of the function tool call generated by the model |
name | String | Yes | The name of the function to run |
type | String | Yes | The type of the function tool call, always function_call |
id | String | No | The unique ID of the function tool call |
status | String | No | The status of the item. Possible values: in_progress , completed , or incomplete |
Computer Tool Call¶
Property | Type | Required | Description |
---|---|---|---|
action | Object | Yes | The computer interaction operation, such as click, drag, etc. |
call_id | String | Yes | The identifier used when the response tool call output is generated |
id | String | Yes | The unique ID of the computer call |
pending_safety_checks | Array | Yes | Pending safety checks for the computer call |
status | String | Yes | The status of the item. Possible values: in_progress , completed , or incomplete |
type | String | Yes | The type of the computer call, always computer_call |
Computer Operation Types:
Operation Type | Description |
---|---|
click | Mouse click operation |
double_click | Mouse double-click operation |
drag | Drag operation |
keypress | Key operation |
move | Mouse move operation |
screenshot | Screenshot operation |
scroll | Scroll operation |
type | Text input operation |
wait | Wait operation |
Computer Tool Call Output¶
Property | Type | Required | Description |
---|---|---|---|
call_id | String | Yes | The ID of the computer tool call that generated the output |
output | Object | Yes | The computer screen capture image for computer use tools |
type | String | Yes | The type of the computer tool call output, always computer_call_output |
acknowledged_safety_checks | Array | No | Safety checks reported by the API that have been confirmed by the developer |
id | String | No | The ID of the computer tool call output |
status | String | No | The status of the input message. Possible values: in_progress , completed , or incomplete |
Function Tool Call Output¶
Property | Type | Required | Description |
---|---|---|---|
call_id | String | Yes | The unique ID of the function tool call generated by the model |
output | String | Yes | The JSON string of the function tool call output |
type | String | Yes | The type of the function tool call output, always function_call_output |
id | String | No | The unique ID of the function tool call output |
status | String | No | The status of the item. Possible values: in_progress , completed , or incomplete |
Reasoning Related Items¶
Property | Type | Required | Description |
---|---|---|---|
id | String | Yes | The unique identifier of the reasoning content |
summary | Array | Yes | The reasoning text content |
type | String | Yes | The type of the object, always reasoning |
encrypted_content | String or null | No | The encrypted version of the reasoning item - filled when generating a response with the reasoning.encrypted_content parameter |
status | String | No | The status of the item. Possible values: in_progress , completed , or incomplete |
Reasoning Summary:
Property | Type | Required | Description |
---|---|---|---|
text | String | Yes | A brief summary of the reasoning used by the model when generating the response |
type | String | Yes | The type of the object, always summary_text |
Item References¶
Property | Type | Required | Description |
---|---|---|---|
id | String | Yes | The ID of the item to reference |
type | String | No | The type of the item to reference, always item_reference |
model¶
Type: String
Required: Yes
The model ID used to generate the response, e.g., gpt-4.1 or o3. OpenAI provides various models with different capabilities, performance characteristics, and price points. Please refer to the model guide to browse and compare available models.
include¶
Type: Array or null
Required: No
Specify additional output data to include in the model response. Currently supported values include:
Value | Description |
---|---|
file_search_call.results |
Includes search results for file search tool calls |
message.input_image.image_url |
Includes the image URL in the input message |
computer_call_output.output.image_url |
Includes the image URL in the computer call output |
reasoning.encrypted_content |
Includes the encrypted version of reasoning tokens in the reasoning item output |
instructions¶
Type: String or null
Required: No
Insert a system (or developer) message as the first item in the model context.
When used with previous_response_id
, the instructions from the previous response will not be carried over to the next response. This makes it easy to switch between system (developer) messages in new responses.
max_output_tokens¶
Type: Integer or null
Required: No
The maximum number of tokens that can be generated for the response, including visible output tokens and reasoning tokens.
metadata¶
Type: Object
Required: No
A collection of 16 key-value pairs that can be attached to the object. This is useful for storing other information about the object in a structured format and querying it via the API or dashboard.
Keys are strings of maximum length 64 characters. Values are strings of maximum length 512 characters.
parallel_tool_calls¶
Type: Boolean or null
Required: No
Default: true
Whether to allow the model to run tool calls in parallel.
previous_response_id¶
Type: String or null
Required: No
The unique ID of the model's previous response. Use this parameter to create multi-turn conversations. Learn more about conversation state.
reasoning¶
Type: Object or null
Required: No
Applies to o-series models
Configuration options for the reasoning model.
Property | Type | Required | Description |
---|---|---|---|
effort | String or null | No | The effort level of reasoning, optional values: low , medium , high . Default is medium . Reducing reasoning effort can speed up the response and reduce the number of tokens used for reasoning |
summary | String or null | No | The summary of reasoning performed by the model. This is useful for debugging and understanding the model's reasoning process. Optional values: auto , concise , detailed |
generate_summary | String or null | No | Deprecated: Please use summary instead. The summary of reasoning performed by the model. Optional values: auto , concise , detailed |
service_tier¶
Type: String or null
Required: No
Default: auto
Specifies the latency tier for processing the request. This parameter is relevant for customers subscribed to the scale tier service:
Value | Description |
---|---|
auto |
If the project is enabled for Scale tier, the system will use scale tier credits until they are exhausted; if the project is not enabled for Scale tier, the request will be processed using the default service tier, with lower normal operation time SLA and no latency guarantees |
default |
The request will be processed using the default service tier, with lower normal operation time SLA and no latency guarantees |
flex |
The request will be processed using the Flex Processing service tier. For more information, please refer to the official documentation |
When this parameter is not set, the default behavior is auto
.
When this parameter is set, the response body will include the used service_tier
.
store¶
Type: Boolean or null
Required: No
Default: true
Whether to store the generated model response for later retrieval via API.
stream¶
Type: Boolean or null
Required: No
Default: false
If set to true, model response data will be streamed to the client in real-time using server-sent events.
temperature¶
Type: Number or null
Required: No
Default: 1
The sampling temperature to use, between 0 and 2. Higher values (e.g., 0.8) make the output more random, while lower values (e.g., 0.2) make it more concentrated and deterministic. We generally recommend changing this value or top_p
, but not both.
text¶
Type: Object
Required: No
Configuration options for the model's text response. It can be pure text or structured JSON data.
Property | Type | Required | Description |
---|---|---|---|
format | Object | No | Specifies the format the model must output |
Configure { "type": "json_schema" }
to enable structured output, ensuring the model will match your provided JSON schema. For more information, please refer to the structured output guide.
The default format is { "type": "text" }
, with no other options.
Not recommended for gpt-4o and newer models:
Set to { "type": "json_object" }
to enable the older JSON mode, ensuring the model's messages are valid JSON. For supported models, it is recommended to use json_schema
.
Text Format Types¶
Text (Text)¶
Property | Type | Required | Description |
---|---|---|---|
type | String | Yes | Defines the response format type. Always text |
JSON Schema (JSON Schema)¶
Property | Type | Required | Description |
---|---|---|---|
name | String | Yes | The name of the response format. Must contain a-z, A-Z, 0-9, or include underscores and hyphens, with a maximum length of 64 |
schema | Object | Yes | The schema of the response format, described as a JSON Schema object |
type | String | Yes | Defines the response format type. Always json_schema |
description | String | No | A description of the purpose of the response format, used by the model to determine how to respond in that format |
strict | Boolean or null | No | Whether to enable strict mode for strict adherence to the schema. Default is false . If set to true , the model will always follow the exact schema defined in the schema field. In strict mode, only a subset of JSON Schema is supported |
JSON Object (JSON Object)¶
Property | Type | Required | Description |
---|---|---|---|
type | String | Yes | Defines the response format type. Always json_object |
Note: If no system or user message explicitly indicates that the model should do so, the model will not generate JSON. For supported models, it is recommended to use json_schema
.
tool_choice¶
Type: String or Object
Required: No
How the model chooses the tool (or multiple tools) to use when generating a response. Please refer to the tools
parameter to learn how to specify the tools that the model can call.
Possible Types¶
Tool Selection Mode (Tool choice mode)¶
Type: String
Controls whether the model calls tools and which tool to call.
Value | Description |
---|---|
none |
The model will not call any tools, but generate a message |
auto |
The model can choose between generating a message or calling one or more tools |
required |
The model must call one or more tools |
Hosted Tool (Hosted tool)¶
Type: Object
Indicates that the model should use a built-in tool to generate a response.
Property | Type | Required | Description |
---|---|---|---|
type | String | Yes | The type of hosted tool the model should use. Allowed values are: file_search , web_search_preview , computer_use_preview |
Function Tool (Function tool)¶
Type: Object
Use this option to force the model to call a specific function.
Property | Type | Required | Description |
---|---|---|---|
name | String | Yes | The name of the function to call |
type | String | Yes | For function calls, the type is always function |
tools¶
Type: Array
Required: No
An array of tools that the model might call when generating a response. You can specify which tool to use by setting the tool_choice
parameter.
You can provide the model with two types of tools:
- Built-in Tools: Tools provided by OpenAI to extend the model's capabilities, such as web search or file search.
- Function Calls (Custom Tools): Functions defined by you, allowing the model to call your own code.
File Search Tool (File search)¶
Type: Object
A tool to search for relevant content in uploaded files.
Property | Type | Required | Description |
---|---|---|---|
type | String | Yes | The type of file search tool, always file_search |
vector_store_ids | Array | Yes | A list of vector store IDs to search |
filters | Object | No | Filters to apply |
max_num_results | Integer | No | The maximum number of results to return. This number should be between 1 and 50 (inclusive) |
ranking_options | Object | No | Search ranking options |
Filter Types¶
Comparison Filter (Comparison Filter)
Property | Type | Required | Description |
---|---|---|---|
key | String | Yes | The key to compare with the value |
type | String | Yes | Specifies the comparison operator: eq , ne , gt , gte , lt , lte - eq: Equal - ne: Not equal - gt: Greater than - gte: Greater than or equal to - lt: Less than - lte: Less than or equal to |
value | String/Number/Boolean | Yes | The value to compare with the property key; supports string, number, or boolean types |
Compound Filter (Compound Filter)
Property | Type | Required | Description |
---|---|---|---|
filters | Array | Yes | An array of filters to combine. Items can be comparison filters or compound filters |
type | String | Yes | Operation type: and or or |
Ranking Options¶
Property | Type | Required | Description |
---|---|---|---|
ranker | String | No | The file search ranking algorithm |
score_threshold | Number | No | The score threshold for file search, a number between 0 and 1. A number closer to 1 will try to return only the most relevant results, but may return fewer results |
Function Tool (Function)¶
Type: Object
Defines functions that the model can optionally call from your own code.
Property | Type | Required | Description |
---|---|---|---|
type | String | Yes | The type of function tool, always function |
name | String | Yes | The name of the function to call |
parameters | Object | Yes | A JSON schema object describing the function parameters |
strict | Boolean | Yes | Whether to force strict parameter validation. Default is true |
description | String | No | The description of the function. The model uses it to determine whether to call the function |
Web Search Tool (Web search preview)¶
Type: Object
This tool searches for relevant results on the web for a response.
Property | Type | Required | Description |
---|---|---|---|
type | String | Yes | The type of web search tool. Optional values: web_search_preview or web_search_preview_2025_03_11 |
search_context_size | String | No | Advanced guidance for the amount of context window space for search. Optional values: low , medium , high . Default is medium |
user_location | Object | No | The user's location |
domains | Array | No | A list of domain names to restrict search to |
User Location¶
Property | Type | Required | Description |
---|---|---|---|
type | String | Yes | The type of location approximation. Always approximate |
city | String | No | A free-text input of the user's city, e.g., "San Francisco" |
country | String | No | The user's two-letter ISO country code, e.g., "US" |
region | String | No | A free-text input of the user's region, e.g., "California" |
timezone | String | No | The user's IANA timezone, e.g., "America/Los_Angeles" |
Computer Use Tool (Computer use preview)¶
Type: Object
Controls tools for a virtual computer.
Property | Type | Required | Description |
---|---|---|---|
type | String | Yes | The type of computer use tool, always computer_use_preview |
display_height | Integer | Yes | The height of the computer display |
display_width | Integer | Yes | The width of the computer display |
environment | String | Yes | The type of computer environment to control |
top_p¶
Type: Number or null
Required: No
Default: 1
An alternative to sampling temperature, called nucleus sampling, where the model considers token results with top_p probability mass. Therefore, 0.1 means only considering tokens with the top 10% probability mass.
We generally recommend changing this value or temperature
, but not both.
truncation¶
Type: String or null
Required: No
Default: disabled
Truncation strategy for model responses:
Value | Description |
---|---|
auto |
If this response and the previous response's context exceeds the model's context window size, the model will truncate the response by deleting input items from the middle of the conversation to fit the context window |
disabled |
If the model response exceeds the model's context window size, the request will fail with a 400 error |
user¶
Type: String
Required: No
A unique identifier for the final user, helping OpenAI monitor and detect abuse behavior.
📥 Response¶
Returns a response object.
Successful Response¶
Returns a response object, and if the request is streamed, returns the response object's streaming sequence.
id¶
- Type: String
- Description: The unique identifier of the response
object¶
- Type: String
- Description: The object type, value is "response"
created_at¶
- Type: Integer
- Description: The timestamp when the response was created
status¶
- Type: String
- Description: The response status, e.g., "completed", "in_progress", etc.
error¶
- Type: Object or null
- Description: If an error occurred, it contains error information
incomplete_details¶
- Type: Object or null
- Description: If the response is incomplete, it contains detailed information
instructions¶
- Type: String or null
- Description: System instructions provided to the model
max_output_tokens¶
- Type: Integer or null
- Description: The maximum number of output tokens
model¶
- Type: String
- Description: The name of the used model
output¶
- Type: Array
- Description: Contains the generated reply and tool calls
- May contain:
- Message objects (
type
: "message") - Tool use objects (
type
: "tool_use")
parallel_tool_calls¶
- Type: Boolean
- Description: Whether parallel tool calls are enabled
previous_response_id¶
- Type: String or null
- Description: The ID of the previous response (for multi-turn conversations)
reasoning¶
- Type: Object
- Description: Reasoning related information
store¶
- Type: Boolean
- Description: Whether to store this response
temperature¶
- Type: Number
- Description: The sampling temperature used
text¶
- Type: Object
- Description: Text output format configuration
tool_choice¶
- Type: String
- Description: Tool selection strategy
tools¶
- Type: Array
- Description: List of available tools
top_p¶
- Type: Number
- Description: Nucleus sampling threshold
truncation¶
- Type: String
- Description: Truncation strategy
usage¶
- Type: Object
- Description: Token usage statistics
- Properties:
input_tokens
: Number of tokens used for inputinput_tokens_details
: Detailed information about input tokensoutput_tokens
: Number of tokens used for outputoutput_tokens_details
: Detailed information about output tokenstotal_tokens
: Total number of tokens
user¶
- Type: String or null
- Description: User identifier
metadata¶
- Type: Object
- Description: Additional metadata information