The Responses API uses a streamlined request format and returns a richer response object compared to Chat Completions. This page covers every key field.
Request Object
A minimal request needs only a model and input:
{
"model": "gpt-4o",
"input": "Explain photosynthesis in one sentence."
}
input field accepts multiple formats:
| Format | Example | Use case |
|---|
| Plain string | "What is 2+2?" | Simple single-turn questions |
| Message array | [{"role": "user", "content": "..."}] | Multi-role conversations with system prompts |
{
"model": "gpt-4o",
"input": "What is the speed of light?"
}
{
"model": "gpt-4o",
"input": [
{ "role": "system", "content": "You are a physics tutor." },
{ "role": "user", "content": "What is the speed of light?" }
]
}
Common Parameters
| Parameter | Type | Default | Description |
|---|
model | string | required | Model ID to use (e.g. "gpt-4o", "gpt-4o-mini") |
input | string | array | required | The user input — a plain string or a messages array |
instructions | string | — | System-level instructions (alternative to a system message in input) |
max_output_tokens | integer | model default | Maximum tokens to generate |
temperature | number | 1.0 | Sampling temperature (0 = deterministic, 2 = very random) |
top_p | number | 1.0 | Nucleus sampling threshold |
stream | boolean | false | Stream output as Server-Sent Events |
tools | array | — | Built-in tools or custom function schemas |
tool_choice | string | object | "auto" | How the model selects tools |
text | object | — | Text output configuration (e.g. {"format": {"type": "json_schema", ...}}) |
previous_response_id | string | — | Chain this response to a previous one for multi-turn |
reasoning | object | — | Reasoning configuration for o-series models (e.g. {"effort": "high"}) |
store | boolean | true | Whether to store the response for multi-turn use |
Use instructions as a cleaner alternative to embedding a system message inside input. It keeps your input focused on the user’s question.
Full Request Example
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.routeway.ai/v1",
api_key=os.getenv("ROUTEWAY_API_KEY")
)
response = client.responses.create(
model="gpt-4o",
instructions="You are a concise assistant. Reply in one paragraph.",
input="Explain how DNS works.",
max_output_tokens=200,
temperature=0.3,
)
print(response.output_text)
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.routeway.ai/v1",
apiKey: process.env.ROUTEWAY_API_KEY,
});
const response = await client.responses.create({
model: "gpt-4o",
instructions: "You are a concise assistant. Reply in one paragraph.",
input: "Explain how DNS works.",
max_output_tokens: 200,
temperature: 0.3,
});
console.log(response.output_text);
curl https://api.routeway.ai/v1/responses \
-H "Authorization: Bearer $ROUTEWAY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o",
"instructions": "You are a concise assistant. Reply in one paragraph.",
"input": "Explain how DNS works.",
"max_output_tokens": 200,
"temperature": 0.3
}'
Response Object
A successful response looks like this:
{
"id": "resp_abc123",
"object": "response",
"created_at": 1749052800,
"model": "gpt-4o-2024-11-20",
"status": "completed",
"output": [
{
"type": "message",
"id": "msg_abc123",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "DNS (Domain Name System) translates human-readable domain names into IP addresses..."
}
]
}
],
"output_text": "DNS (Domain Name System) translates human-readable domain names into IP addresses...",
"usage": {
"input_tokens": 35,
"output_tokens": 62,
"total_tokens": 97
}
}
Key Fields
| Field | Description |
|---|
id | Unique response identifier (used for multi-turn via previous_response_id) |
object | Always "response" |
status | "completed", "failed", "in_progress", or "cancelled" |
output | Array of output items (messages, tool calls, etc.) |
output_text | Convenience field — the concatenated text content from all output messages |
model | The exact model snapshot used |
usage | Token counts for billing |
The output_text field is a shortcut. For simple text responses, use it directly instead of digging into output[0].content[0].text.
Output Item Types
The output array can contain different item types:
| Type | Description |
|---|
message | A text response from the model |
function_call | The model wants to call a custom function you defined |
web_search_call | The model performed a web search (built-in tool) |
file_search_call | The model searched uploaded files (built-in tool) |
code_interpreter_call | The model executed code (built-in tool) |
Status Values
| Status | Meaning |
|---|
"completed" | Response generated successfully |
"failed" | An error occurred during generation |
"in_progress" | Response is still being generated (streaming or background) |
"cancelled" | Response was cancelled before completion |
Always check the status field. A "failed" status means the response was not generated — check the error field on the response object for details.
Accessing the Response Text
The simplest way to get the model’s reply:
text = response.output_text
output array:
for item in response.output:
if item.type == "message":
for content in item.content:
if content.type == "output_text":
print(content.text)
function_call item:
for item in response.output:
if item.type == "function_call":
print(f"Function: {item.name}")
print(f"Arguments: {item.arguments}")
Error Responses
Errors follow the same format as Chat Completions:
{
"error": {
"message": "Invalid model: 'gpt-999'.",
"type": "invalid_request_error",
"code": "model_not_found"
}
}
| HTTP status | Type | Common causes |
|---|
400 | invalid_request_error | Bad parameters, invalid model, context too long |
401 | authentication_error | Missing or invalid API key |
429 | rate_limit_error | Too many requests or insufficient balance |
500 | server_error | Upstream provider error |