Skip to main content

OpenAI Responses API

GoRoute AI Gateway supports OpenAI's next-generation Responses API (POST /v1/responses). Designed as the structural successor to chat completions, the Responses API consolidates instructions, multimodal conversation context, and progressive output items under an object-oriented event paradigm.


Endpoint Specification​

  • HTTP Method: POST
  • Supported Paths:
    • /v1/responses
    • /responses (Unversioned alias)
    • /openai/v1/responses (OpenAI wire compatibility alias)
  • Authentication: Bearer sk-gw-... (Virtual Key or Master Admin Key)
  • Content-Type: application/json

Request & Response Schemas​

Request Schema (CanonicalResponseRequest)​

{
"model": "gpt-4.1",
"instructions": "You are a concise infrastructure assistant.",
"input": "Explain the role of an intelligent proxy in LLM gateways.",
"temperature": 0.5,
"max_output_tokens": 300,
"stream": false
}
FieldTypeRequiredDescription
modelstringYesTarget model (e.g. gpt-4.1, fast, gemini/gemini-2.5-flash).
instructionsstringNoTop-level system directives governing the assistant's behavior.
inputstring | object[]YesUser input string or array of prior conversation message objects.
temperaturefloatNoSampling temperature between 0.0 and 2.0.
max_output_tokensintegerNoMaximum token ceiling for generated output items.
toolsarrayNoFunction/tool definitions forwarded to the selected upstream provider.
extra_bodyobjectNoProvider-specific parameters merged without clobbering core request fields.
streambooleanNoWhen true, streams incremental lifecycle events via SSE.

Synchronous Response Schema (CanonicalResponseOutput)​

{
"id": "resp_98a7bc12-f049-411a-8c9e-28491a0123fe",
"object": "response",
"created_at": 1740000000,
"model": "gpt-4.1",
"status": "completed",
"usage": {
"prompt_tokens": 24,
"completion_tokens": 48,
"total_tokens": 72
},
"output": [
{
"id": "msg_89f1a23c_0",
"type": "message",
"status": "completed",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "An intelligent proxy acts as an abstraction layer between client applications and heterogeneous upstream model providers..."
}
]
}
]
}

Streaming Event Lifecycle​

When "stream": true is enabled, the Responses API delivers granular lifecycle events over Server-Sent Events (text/event-stream):

event: response.created
data: {"response":{"id":"resp_...","object":"response","status":"in_progress","model":"gpt-4.1","created_at":1740000000}}

event: response.output_item.added
data: {"output_index":0,"item":{"id":"msg_...","type":"message","status":"in_progress","role":"assistant"}}

event: response.content_part.added
data: {"output_index":0,"content_index":0,"part":{"type":"output_text","text":""}}

event: response.text.delta
data: {"output_index":0,"content_index":0,"delta":"An intelligent"}

event: response.text.delta
data: {"output_index":0,"content_index":0,"delta":" proxy manages..."}

event: response.output_text.done
data: {"output_index":0,"content_index":0,"text":"An intelligent proxy manages..."}

event: response.output_item.done
data: {"output_index":0,"item":{"id":"msg_...","type":"message","status":"completed","role":"assistant","content":[{"type":"output_text","text":"An intelligent proxy manages..."}]}}

event: response.completed
data: {"response":{"id":"resp_...","object":"response","status":"completed","model":"gpt-4.1","created_at":1740000000,"output":[...]}}

event: response.done
data: {}

Code Examples​

# 1. Non-streaming call
curl -X POST http://localhost:8080/v1/responses \
-H "Authorization: Bearer sk-gw-prod-7f9a2b8c4d1e" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4.1",
"instructions": "Be strictly factual and brief.",
"input": "What is the capital of Australia?",
"stream": false
}'

# 2. SSE Streaming call via /openai/v1/responses
curl -X POST http://localhost:8080/openai/v1/responses \
-H "Authorization: Bearer sk-gw-prod-7f9a2b8c4d1e" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4.1",
"instructions": "Count from 1 to 5.",
"input": "Begin counting.",
"stream": true
}'