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. When the model's upstream serves the Responses API itself, AISIX forwards the request there. Otherwise 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.

Export the gateway connection and request values:

# AISIX_PROXY has no trailing slash or endpoint path such as /v1.
# The local quickstarts use http://127.0.0.1:3000.
export AISIX_PROXY="YOUR_AISIX_GATEWAY_ORIGIN"
export AISIX_API_KEY="YOUR_CALLER_API_KEY"
export AISIX_MODEL="gpt-4o-prod"

Send a Responses Request

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

curl -sS -X POST "${AISIX_PROXY}/v1/responses" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"${AISIX_MODEL}"'",
    "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-prod",
  "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:

Upstream	Behavior
Serves the Responses API	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.
Does not serve it	AISIX translates supported Responses fields into the gateway's chat format, dispatches through the provider adapter, and returns a Responses API result.

Which one applies is decided per provider key. Without a surface declaration, AISIX forwards natively for the openai provider and translates for every other provider. That default is wrong in both directions for some endpoints: an OpenAI-compatible endpoint reached through the openai provider with a custom api_base may have no /v1/responses route, and an endpoint on another provider may serve one. Declare the key's API surfaces to say which it is — see Declare the API Surfaces.

The bridge supports common text, tool call, tool result, sampling, and streaming fields. It carries reasoning.effort into the canonical chat request as reasoning_effort; provider adapters that support an effort control then translate it to their wire field. For example, Anthropic receives output_config.effort. You can also rewrite the value per direct model with Reasoning Effort Mapping. 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 translated requests:

• reasoning members other than effort, such as summary
• 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. A buffered frame that AISIX cannot parse is dropped rather than released unscanned, and a response left with nothing to return is refused with 422. See Frames AISIX Cannot Scan.

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.

On bridged providers whose token accounting differs from OpenAI's, AISIX converts the counts into the Responses API shape: input_tokens is the full input, input_tokens_details.cached_tokens is the cache-read subset of it, input_tokens_details.cache_creation_tokens is the cache-write subset when the upstream reported one, and total_tokens is input_tokens + output_tokens. See Token Usage for a worked example with an Anthropic upstream — it is written in Chat Completions field names, which map to these one for one (prompt_tokens to input_tokens, completion_tokens to output_tokens, prompt_tokens_details to input_tokens_details, completion_tokens_details to output_tokens_details). One shape difference: output_tokens_details.reasoning_tokens is always present on a Responses reply, including when it is 0, whereas Chat Completions omits the block entirely.

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.