Responses API

The Responses API is OpenAI's response-generation endpoint for applications that use its input/output item format instead of the chat-completions message format. AISIX AI Gateway exposes this route for Responses API clients while keeping caller authentication, model aliases, upstream credentials, and gateway policy in the gateway.

Use this route when an application or tool already speaks the Responses API. For OpenAI-backed models, AISIX forwards the request to the upstream Responses API. For other providers, AISIX translates the request through the provider adapter and returns a Responses API result to the caller.

Prerequisites

Before starting, prepare the following:

• A running AISIX gateway that can serve proxy requests.
• A caller API key that can access the model alias.
• A model alias backed by a provider that can handle the translated request shape.

Send a Responses Request

Send the request through the gateway proxy with the AISIX model alias in the request body:

curl -sS -X POST "http://127.0.0.1:3000/v1/responses" \
  -H "Authorization: Bearer YOUR_CALLER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-prod",
    "input": "Say hello from AISIX."
  }'

AISIX resolves the model alias and chooses the provider path for the selected model. OpenAI-backed models are forwarded to the upstream Responses API without body translation. Other providers use the cross-provider bridge.

The response body is returned in the upstream Responses API format:

{
  "id": "resp_***",
  "object": "response",
  "model": "gpt-4o-mini-2024-07-18",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Hello from AISIX."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 12,
    "output_tokens": 5,
    "total_tokens": 17
  }
}

Provider Behavior

AISIX handles Responses requests in two ways:

Model provider	Behavior
OpenAI	AISIX rewrites the request model to the upstream model ID and forwards the request to the upstream Responses API. Upstream-specific Responses features pass through when the upstream supports them.
Other providers	AISIX translates supported Responses fields into the gateway's chat format, dispatches through the provider adapter, and returns a Responses API result.

The bridge supports common text, tool call, tool result, sampling, and streaming fields. OpenAI-only Responses features that do not have a provider-neutral chat equivalent are not forwarded on the bridged path.

The following fields are ignored on bridged non-OpenAI requests:

• reasoning
• store
• previous_response_id
• hosted tools such as web_search, file_search, and code_interpreter
• text, metadata, service_tier, and other OpenAI-specific controls

Policy and Usage Behavior

Input guardrails can inspect request text before AISIX calls the provider. Output guardrails can inspect non-streaming responses before content reaches the caller.

If an output guardrail blocks the response, AISIX returns a content-policy error to the caller and records the blocked request for observability.

For streaming requests, AISIX preserves the Responses SSE shape. On OpenAI-backed models, AISIX can pass through upstream SSE. On bridged providers, AISIX encodes provider stream chunks into Responses events. If output guardrails are enabled, AISIX buffers the stream for policy inspection before returning it or blocking it.

For successful responses, the gateway records usage when the upstream response includes token usage. Streaming usage is emitted when AISIX receives terminal usage information from the stream.

Next Steps

You have now seen when to use Responses API through AISIX and how provider handling differs between direct forwarding and bridging. Next, continue with Text Completions for the legacy completions route, or Streaming when your Responses API client depends on SSE behavior.