Responses API Beta Basic Usage | Simple Text Requests | OpenRouter

Beta API

This API is in beta stage and may have breaking changes.

The Responses API Beta supports both simple string input and structured message arrays, making it easy to get started with basic text generation.

Simple String Input

The simplest way to use the API is with a string input:

Structured Message Input

For more complex conversations, use the message array format:

Response Format

The API returns a structured response with the generated content:

1 {
2   "id": "resp_1234567890",
3   "object": "response",
4   "created_at": 1234567890,
5   "model": "openai/o4-mini",
6   "output": [
7     {
8       "type": "message",
9       "id": "msg_abc123",
10       "status": "completed",
11       "role": "assistant",
12       "content": [
13         {
14           "type": "output_text",
15           "text": "The meaning of life is a philosophical question that has been pondered for centuries...",
16           "annotations": []
17         }
18       ]
19     }
20   ],
21   "usage": {
22     "input_tokens": 12,
23     "output_tokens": 45,
24     "total_tokens": 57
25   },
26   "status": "completed"
27 }

Streaming Responses

Enable streaming for real-time response generation:

Example Streaming Output

The streaming response returns Server-Sent Events (SSE) chunks:

data: {"type":"response.created","response":{"id":"resp_1234567890","object":"response","status":"in_progress"}}
data: {"type":"response.output_item.added","response_id":"resp_1234567890","output_index":0,"item":{"type":"message","id":"msg_abc123","role":"assistant","status":"in_progress","content":[]}}
data: {"type":"response.content_part.added","response_id":"resp_1234567890","output_index":0,"content_index":0,"part":{"type":"output_text","text":""}}
data: {"type":"response.content_part.delta","response_id":"resp_1234567890","output_index":0,"content_index":0,"delta":"Once"}
data: {"type":"response.content_part.delta","response_id":"resp_1234567890","output_index":0,"content_index":0,"delta":" upon"}
data: {"type":"response.content_part.delta","response_id":"resp_1234567890","output_index":0,"content_index":0,"delta":" a"}
data: {"type":"response.content_part.delta","response_id":"resp_1234567890","output_index":0,"content_index":0,"delta":" time"}
data: {"type":"response.output_item.done","response_id":"resp_1234567890","output_index":0,"item":{"type":"message","id":"msg_abc123","role":"assistant","status":"completed","content":[{"type":"output_text","text":"Once upon a time, in a world where artificial intelligence had become as common as smartphones..."}]}}
data: {"type":"response.done","response":{"id":"resp_1234567890","object":"response","status":"completed","usage":{"input_tokens":12,"output_tokens":45,"total_tokens":57}}}
data: [DONE]

Common Parameters

Parameter	Type	Description
`model`	string	Required. Model to use (e.g., `openai/o4-mini`)
`input`	string or array	Required. Text or message array
`stream`	boolean	Enable streaming responses (default: false)
`max_output_tokens`	integer	Maximum tokens to generate
`temperature`	number	Sampling temperature (0-2)
`top_p`	number	Nucleus sampling parameter (0-1)

Error Handling

Handle common errors gracefully:

Multiple Turn Conversations

Since the Responses API Beta is stateless, you must include the full conversation history in each request to maintain context:

Required Fields

The id and status fields are required for any assistant role messages included in the conversation history.

Conversation History

Always include the complete conversation history in each request. The API does not store previous messages, so context must be maintained client-side.

Next Steps

Learn about Reasoning capabilities
Explore Tool Calling functionality
Try Web Search integration

1	{
2	"id": "resp_1234567890",
3	"object": "response",
4	"created_at": 1234567890,
5	"model": "openai/o4-mini",
6	"output": [
7	{
8	"type": "message",
9	"id": "msg_abc123",
10	"status": "completed",
11	"role": "assistant",
12	"content": [
13	{
14	"type": "output_text",
15	"text": "The meaning of life is a philosophical question that has been pondered for centuries...",
16	"annotations": []
17	}
18	]
19	}
20	],
21	"usage": {
22	"input_tokens": 12,
23	"output_tokens": 45,
24	"total_tokens": 57
25	},
26	"status": "completed"
27	}