OpenAI Responses

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 works with every chat model and every gateway feature.

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

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."}'

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)

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);

Request body

The body is OpenAI’s Responses request.

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.

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.

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.

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.

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 for when an answer can still fail to parse, and Model support for how each provider handles a schema.

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.

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 on Chat Completions.

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.

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.

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.

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.

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, the format every feature supports.
• Chat Completions: the fields the gateway reads.