---
title: "OpenAI Responses"
subtitle: "Send OpenAI Responses API requests through the gateway."
---

Use this format if your code already calls OpenAI's Responses API. Point the OpenAI SDK at the gateway and keep calling `responses.create`. For new code, [Chat Completions](/docs/ai-gateway/requests/chat-completions) works with every chat model and every gateway feature.

`POST https://gateway.respan.ai/v1/responses`

<Tabs>
<Tab title="cURL">
```bash
curl https://gateway.respan.ai/v1/responses \
  -H "Authorization: Bearer $RESPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-5.5", "input": "Explain why small language models are useful."}'
```
</Tab>
<Tab title="Python">
```python
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://gateway.respan.ai/v1",
    api_key=os.environ["RESPAN_API_KEY"],
)

response = client.responses.create(
    model="gpt-5.5",
    input="Explain why small language models are useful.",
)
print(response.output_text)
```
</Tab>
<Tab title="TypeScript">
```typescript
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://gateway.respan.ai/v1",
  apiKey: process.env.RESPAN_API_KEY,
});

const response = await client.responses.create({
  model: "gpt-5.5",
  input: "Explain why small language models are useful.",
});
console.log(response.output_text);
```
</Tab>
</Tabs>

## Request body

The body is OpenAI's Responses request.

| Field | Type | Description |
|---|---|---|
| `model` | string | A model ID from the [catalog](/docs/ai-gateway/models/overview). Required. |
| `input` | string or array | The prompt, or a list of input items. Required. |
| `instructions` | string | System instructions. |
| `stream` | boolean | `true` returns Responses server-sent events. See [Streaming](#streaming). |
| `tools` | array | Function tools. See [Tool calling](#tool-calling). |
| `text.format` | object | Structured output. See [Structured outputs](#structured-outputs). |
| `reasoning.effort` | string | Reasoning effort. |
| `max_output_tokens`, `temperature`, `top_p` | | Standard sampling settings. |
| `respan_params` | object | Respan params, at the top level or inside `metadata`. See [Respan params](#respan-params). |

OpenAI's built-in tools (web search, file search, computer use, code interpreter) and fields such as `include` and `truncation` reach OpenAI models unchanged. Sent to another vendor's model, a field with no equivalent there is refused with `400` and named in the error, not dropped. See [known gaps](/docs/oss-gateway/api-formats#chat-gaps).

## Streaming

Set `stream: true` and the gateway returns Responses server-sent events, whichever provider answers. Events are typed, such as `response.output_text.delta` for each piece of text, and the stream ends with `response.completed`.

```python
stream = client.responses.create(
    model="gpt-5.5",
    input="Write a haiku about routers.",
    stream=True,
)
for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="")
    elif event.type == "response.completed":
        print()
```

For errors before and during a stream, cancellation and billing, and the gateway's fixed 600 second timeout, see [Chat Completions](/docs/ai-gateway/requests/chat-completions#stream-errors).

## Structured outputs

In the Responses format, a JSON schema goes in `text.format` with `type: "json_schema"`, and the model answers with JSON that matches it.

```python
import json

response = client.responses.create(
    model="gpt-5.5",
    input="Ada Lovelace was born in London in 1815.",
    text={
        "format": {
            "type": "json_schema",
            "name": "person",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "birth_year": {"type": "integer"},
                    "city": {"type": "string"},
                },
                "required": ["name", "birth_year", "city"],
                "additionalProperties": False,
            },
        }
    },
)
print(json.loads(response.output_text))
```

The gateway returns the answer as the provider sent it and doesn't repair JSON. See [Invalid JSON](/docs/ai-gateway/requests/chat-completions#invalid-json) for when an answer can still fail to parse, and [Model support](/docs/ai-gateway/requests/chat-completions#model-support) for how each provider handles a schema.

{/* REVIEW: new section. Source pages only describe response_format on Chat Completions; confirm text.format is translated for other vendors' models on /v1/responses (or refused with 400 like other fields with no equivalent). */}

## Tool calling

Function tools use the Responses shape: `name`, `description` and `parameters` sit on the tool itself. The model's call comes back as a `function_call` item in `output`, and you send the result back as a `function_call_output` input item with the same `call_id`.

```python
import json

tools = [{
    "type": "function",
    "name": "get_weather",
    "description": "Get the current weather for a city",
    "parameters": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"],
    },
}]
input_items = [{"role": "user", "content": "What is the weather in Paris?"}]

response = client.responses.create(model="gpt-5.5", input=input_items, tools=tools)
input_items += response.output

for item in response.output:
    if item.type == "function_call":
        args = json.loads(item.arguments)
        result = {"temp_c": 18, "sky": "clear"}  # your function's output
        input_items.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": json.dumps(result),
        })

final = client.responses.create(model="gpt-5.5", input=input_items, tools=tools)
print(final.output_text)
```

For the agent loop, `tool_choice`, routing by tool support, and how tool calls are logged and billed, see [Tool calling](/docs/ai-gateway/requests/chat-completions#tool-calling) on Chat Completions.

{/* REVIEW: new section. Source pages describe tool translation and server tools for Chat Completions only; confirm Responses function tools are translated for other vendors' models and whether server tools run on /v1/responses. */}

## Pin a provider

The `X-Respan-Route-Provider` header sends a Responses request to a specific provider, such as `azure`, `openrouter`, `perplexity`, or `xai`. You can also pin one by sending a provider offering as `model`, such as `azure/gpt-5.5`.

```bash
curl https://gateway.respan.ai/v1/responses \
  -H "Authorization: Bearer $RESPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Respan-Route-Provider: azure" \
  -d '{"model": "gpt-5.5", "input": "Hello!"}'
```

See [Provider routing](/docs/ai-gateway/routing/provider-routing).

## Respan params

Send Respan params in a top-level `respan_params` object (with `extra_body`), inside `metadata.respan_params`, or in the `X-Data-Respan-Params` header. The gateway removes them before the provider sees the body.

```python
response = client.responses.create(
    model="gpt-5.5",
    input="Hello!",
    extra_body={"respan_params": {"customer_identifier": "user_8842", "thread_identifier": "ticket_1042"}},
)
```

See [Respan params](/docs/ai-gateway/customers/respan-params).

## Response

The body is a Responses `response` object. Every response carries `X-Respan-Log-Id` and `X-Respan-Gateway-Request-Id`, and the call is logged as a Responses request with its reply.

## Next steps

- [Chat Completions](/docs/ai-gateway/requests/chat-completions), the format every feature supports.
- [Chat Completions](/docs/ai-gateway/requests/chat-completions#request-body): the fields the gateway reads.