OpenAI's newer generation API, recommended for GPT models. Unlike Chat Completions, it lets you use reasoning and tools together and includes built-in web search. Codex uses this API too.POST https://studio.dataeyes.ai/v1/responses
Quick example#
{
"id": "resp_xxx",
"object": "response",
"created_at": 1792856704,
"status": "completed",
"model": "gpt-6-luna",
"output": [
{
"id": "msg_xxx",
"type": "message",
"role": "assistant",
"status": "completed",
"content": [
{
"type": "output_text",
"text": "I’m ChatGPT, an AI assistant here to help answer questions and tackle tasks.",
"annotations": []
}
]
}
],
"usage": {
"input_tokens": 22,
"input_tokens_details": { "cached_tokens": 0 },
"output_tokens": 21,
"output_tokens_details": { "reasoning_tokens": 0 },
"total_tokens": 43
}
}
The model's reply is in the output array; the item with type message is the final answer. The SDK's output_text joins all text for you.Request parameters#
| Parameter | Type | Required | Description |
|---|
model | string | Yes | Model name, exactly as shown in the Model Hub |
input | string / array | Yes | Input. A string is a single user message; an array can hold multi-turn messages, images and tool results |
instructions | string | No | System instructions, equivalent to the system message in Chat Completions |
stream | boolean | No | If true, the response is streamed as SSE events |
max_output_tokens | integer | No | Upper limit on output tokens (including reasoning tokens) |
reasoning | object | No | Reasoning settings, such as {"effort": "low"}. See "Reasoning" below |
tools | array | No | Available tools: custom functions (function) and web search (web_search) |
tool_choice | string / object | No | auto (default), none, required, or a specific tool |
For multi-turn conversations, put the history in the input array in order, for example:"input": [
{"role": "user", "content": "My name is Li."},
{"role": "assistant", "content": "Hi, Li!"},
{"role": "user", "content": "What is my name?"}
]
Streaming#
With "stream": true, the response is returned as an event stream. Text deltas arrive in response.output_text.delta events, and response.completed (with the full response and usage) comes last.response.created → response.in_progress → response.output_item.added → response.content_part.added
→ response.output_text.delta (repeated) → response.output_text.done → response.content_part.done
→ response.output_item.done → response.completed
event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_xxx","output_index":0,"content_index":0,"delta":"…"}
Reasoning#
Use reasoning.effort to control how much the model thinks (low, medium, high).output starts with a reasoning item, followed by the final answer. Reasoning tokens are reported in usage.output_tokens_details.reasoning_tokens and billed as output:{
"output": [
{ "id": "rs_xxx", "type": "reasoning", "summary": [] },
{
"id": "msg_xxx",
"type": "message",
"role": "assistant",
"content": [{ "type": "output_text", "text": "30" }]
}
],
"usage": {
"input_tokens": 27,
"output_tokens": 15,
"output_tokens_details": { "reasoning_tokens": 8 },
"total_tokens": 42
}
}
Function calling#
Unlike Chat Completions, function definitions in Responses are flat (name and parameters sit directly on the tool object), and they can be used together with reasoning.Step 1: send the request with function definitionsoutput contains a function_call item:{
"output": [
{
"id": "fc_xxx",
"type": "function_call",
"status": "completed",
"call_id": "call_TRQB8qM768eHrdYYwTDvBt06",
"name": "get_weather",
"arguments": "{\"city\":\"Shanghai\"}"
}
]
}
Step 2: run the function and send the result backPut the original question, the function_call item and a function_call_output item (with the matching call_id) in input:The model answers: Shanghai is cloudy today, with a temperature of 22°C (72°F).Web search#
Add {"type": "web_search"} to tools. The model decides what to search for, reads pages, and cites its sources in the answer.output contains one or more web_search_call items (searching or opening pages) followed by the final message. Sources are in annotations:{
"output": [
{
"id": "ws_xxx",
"type": "web_search_call",
"status": "completed",
"action": { "type": "search", "queries": ["AI industry news October 24 2026 artificial intelligence today"] }
},
{
"id": "msg_xxx",
"type": "message",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "…",
"annotations": [
{
"type": "url_citation",
"start_index": 203,
"end_index": 289,
"title": "…",
"url": "https://www.axios.com/…"
}
]
}
]
}
]
}
Web search usually takes tens of seconds, so set a long enough client timeout. Retrieved page content counts as input tokens; a single request can reach tens of thousands of input tokens.
Use input_image in a message's content:image_url can also be a Base64 data URL (data:image/jpeg;base64,...).Response fields#
| Field | Description |
|---|
id | Unique ID of the response |
status | completed, incomplete (for example, the token limit was reached), or failed |
output | Array of output items; type can be message, reasoning, function_call or web_search_call |
output[].content[].text | Answer text (in message items) |
output[].content[].annotations | Cited sources (with web search) |
usage.input_tokens | Input tokens; input_tokens_details.cached_tokens is the cached part |
usage.output_tokens | Output tokens (including reasoning tokens) |
usage.output_tokens_details.reasoning_tokens | Reasoning tokens |
FAQ#