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 model aliases whose configured provider is OpenAI and whose upstream supports the Responses API.

Use this route when an application already depends on the OpenAI Responses API and should still use AISIX caller authentication, model aliases, upstream credentials, and gateway policy. This route is provider-specific. It is not a cross-provider compatibility layer, and OpenAI-compatible chat-completions vendors are not automatically supported.

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 whose configured provider is OpenAI.

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, verifies that the resolved model is configured with the OpenAI provider, rewrites the request model to the upstream model ID, and forwards the request to the upstream Responses API.

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
  }
}

OpenAI Provider Requirement

The Responses API route is available only for model aliases whose configured provider is OpenAI.

This is stricter than using the OpenAI-compatible adapter. An OpenAI-compatible vendor can work on the chat-completions route and still be rejected on the Responses API route because its configured provider is not OpenAI.

When the resolved model is not configured with the OpenAI provider, AISIX returns 400 before sending the request upstream.

For supported OpenAI provider models, AISIX forwards the request to the upstream Responses API. The response returns as JSON or streaming SSE depending on the request.

This path is a provider-specific proxy, not a cross-provider compatibility layer.

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 can pass through upstream SSE. If output guardrails are enabled, AISIX buffers the stream for policy inspection before returning it or blocking it.

For non-streaming successful responses, the gateway records usage when the upstream response includes token usage. Streaming usage attribution is not available for this route; use a non-streaming request when gateway-side usage attribution matters.

Next Steps

You have now seen when to use Responses API through AISIX and why it is narrower than chat completions. Next, continue with Audio APIs to review audio request behavior through AISIX.