Responses

Use the stateless subset of the OpenAI Responses API for text, multimodal input, tools, and streaming.

`POST /v1/responses`

Creates an OpenAI Responses-compatible result. The endpoint supports synchronous JSON and SSE, but intentionally exposes only stateless calls.

Stateless subset

Omit stateful fields or send store: false. The gateway never lets an upstream account persist your response by default.

POST /v1/responses
Authorization: Bearer $API_KEY
Content-Type: application/json

Request body

Field	Type	Required	Description
`model`	string	Yes	Complete public model ID.
`input`	string or array	Yes for a normal call	Text or Responses input items.
`instructions`	string	No	System or developer instructions.
`stream`	boolean	No	Return Responses SSE events when `true`.
`max_output_tokens`	integer	No	Maximum generated output, including reasoning tokens.
`temperature`	number	No	Sampling temperature when supported.
`top_p`	number	No	Nucleus sampling when supported.
`tools`	array	No	Function or protocol-native built-in tools.
`tool_choice`	string or object	No	Tool-selection policy.
`reasoning`	object	No	Model-specific reasoning effort and summary options.
`text`	object	No	Text output format, including compatible structured-output schemas.
`include`	string[]	No	Additional protocol-native output data to include.
`parallel_tool_calls`	boolean	No	Allow compatible models to emit parallel tool calls.
`user`	string	No	Stable end-user identifier.
`store`	boolean	No	Must be omitted or `false`.
`background`	boolean	No	Must be omitted or `false`.

input can be a plain string or an array containing message, function_call, function_call_output, and supported protocol-native items. Message content can contain input_text and input_image parts.

Synchronous example

curl "http://127.0.0.1:11113/v1/responses" -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" -d '{
  "model": "openai/gpt-5.2",
  "instructions": "Answer concisely.",
  "input": "What is a model gateway?",
  "store": false
}'

A typical response contains a response ID, creation time, status, output items, and usage:

{
  "id": "resp_req_01J...",
  "object": "response",
  "created_at": 1767225600,
  "status": "completed",
  "model": "openai/gpt-5.2",
  "output": [
    {
      "id": "msg_req_01J..._0",
      "type": "message",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "A model gateway provides one API over multiple AI models.",
          "annotations": []
        }
      ]
    }
  ],
  "store": false,
  "usage": {
    "input_tokens": 12,
    "input_tokens_details": { "cached_tokens": 0 },
    "output_tokens": 13,
    "output_tokens_details": { "reasoning_tokens": 0 },
    "total_tokens": 25
  }
}

model is rewritten to the public ID and store remains false.

Streaming

Set stream: true to receive named SSE events. Handle item-level deltas and wait for a terminal response.completed, response.incomplete, response.failed, or error event. Same-protocol streams preserve provider-native event fields.

event: response.output_text.delta
data: {"type":"response.output_text.delta","sequence_number":4,"item_id":"msg_req_01J..._0","output_index":0,"content_index":0,"delta":"Hello","logprobs":[]}

event: response.completed
data: {"type":"response.completed","sequence_number":20,"response":{"id":"resp_req_01J...","status":"completed"}}

A stream normally begins with response.created and response.in_progress, emits item/content lifecycle events, and ends at the terminal response event. Do not require a [DONE] marker.

Tools and protocol fidelity

On a same-protocol route, built-in tools and provider extensions are passed through, including compatible reasoning and search controls. On a cross-protocol route, only function tools have a shared representation; built-in tools, file references, audio items, and other protocol-only items can be named in x-dropped-params.

Encrypted reasoning context can be returned in reasoning.encrypted_content. Send the item back unchanged when the same protocol requires reasoning continuity. The gateway preserves it in transit but replaces it with a size placeholder in request logs.

Unsupported state

The following values return 400 stateful_not_supported:

store: true
background: true
A non-null previous_response_id
A non-null conversation

The gateway does not expose Responses retrieval, deletion, compaction, or background-result endpoints. Client routing fields and paid service tiers are also rejected.