Request & Response

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 Formats

The 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

String input:

{
  "model": "gpt-4o",
  "input": "What is the speed of light?"
}

Message array input (with system prompt):

{
  "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

Python
Node.js
cURL

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

For more control, iterate over the output array:

for item in response.output:
    if item.type == "message":
        for content in item.content:
            if content.type == "output_text":
                print(content.text)

When the model calls a function, the output includes a 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

See the Errors page for the full list and handling guidance.

Get Started

Platform Details

Help & Resources

Core Concepts

Account Management

Guides

Request Object

Input Formats

Common Parameters

Full Request Example

Response Object

Key Fields

Output Item Types

Status Values

Accessing the Response Text

Error Responses

​Request Object

​Input Formats

​Common Parameters

​Full Request Example

​Response Object

​Key Fields

​Output Item Types

​Status Values

​Accessing the Response Text

​Error Responses

Request Object

Input Formats

Common Parameters

Full Request Example

Response Object

Key Fields

Output Item Types

Status Values

Accessing the Response Text

Error Responses