Text

Send chat requests to any provider's models with one OpenAI-compatible call.

Text is the default modality. You send a Chat Completions request, the gateway routes the model to a provider, translates the request into that provider’s format, and returns the answer in OpenAI’s shape. Every call is logged as a trace with its cost.

Pick a model: filter by input and output type on the model catalog , or read Models for how model ids work.

Quickstart

Terminal


curl https://gateway.respan.ai/v1/chat/completions \
  -H "Authorization: Bearer $RESPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [{"role": "user", "content": "Write a haiku about latency."}]
  }'

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.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Write a haiku about latency."}],
)
print(response.choices[0].message.content)

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.chat.completions.create({
  model: "gpt-5.5",
  messages: [{ role: "user", content: "Write a haiku about latency." }],
});
console.log(response.choices[0].message.content);

The full request and response schema is on Chat Completions. The same models are also served through Responses, Anthropic Messages (POST /v1/messages) and Gemini (generateContent).

Options

Parameter	Type	Default	Description
`model`	string	required	Any chat model in the catalog, from any provider.
`stream`	boolean	`false`	Return the answer as server-sent events.
`reasoning_effort`	string	provider default	How hard a reasoning model thinks, mapped across providers.
`response_format`	object	text	Constrain the answer to JSON or a JSON schema.
`tools`	array	none	Functions the model may call.
Respan parameters	various	none	Customer, metadata, thread and trace names, logging. Never sent to the provider.

Every other OpenAI Chat Completions field is passed through when the target provider takes it. See the Chat Completions request body for each field.

Stream the answer

Set stream: true to receive the answer as server-sent events. The gateway streams from every chat provider, including ones that answer whole.

Python


stream = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Write a haiku about latency."}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

See Streaming for usage chunks.

Use any provider’s models

Change model to call another provider. The OpenAI SDK can call a Claude or Gemini model, and the gateway translates messages, tools, images and documents into that provider’s format. The Anthropic SDK, pointed at /v1/messages, can call non-Anthropic models the same way.

When a request carries a field the target format has no equivalent for, the gateway answers 400 and names the field instead of dropping it. The OSS API formats page lists the known gaps.

Reasoning models

reasoning_effort maps across providers where the target has an equivalent:

OpenAI Chat	Anthropic	Gemini
`reasoning_effort: "none"`	thinking disabled	`thinkingBudget: 0`
`reasoning_effort` minimal to high	`output_config.effort`	`thinkingLevel`

A token budget can’t be expressed in Chat Completions. To set one, use the Anthropic Messages format with thinking.budget_tokens.

Respan parameters

Respan parameters ride in the request body next to the OpenAI ones and never reach the provider. With the OpenAI SDK, pass them in extra_body, or send them base64-encoded in the X-Data-Respan-Params header.

Python


response = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Hi"}],
    extra_body={
        "customer_identifier": "user_123",
        "metadata": {"feature": "onboarding"},
    },
)

The same parameters work on every modality: images, video, audio, realtime, embeddings and decisions. See Respan parameters for the full list.

Pricing and logs

Each request is one trace. Its root is a chat row, named by the X-Respan-Log-Id response header, with the messages, the reply, tokens, latency and cost.
On Respan’s credits, a call is held before it is sent, then charged from the provider’s own usage report at the model’s catalog price when it ends. See Pricing.
On your own provider key (BYOK), the provider bills you, and the call is still logged and counted against your limits.
A streamed answer that reports no usage is charged its prompt and what it streamed.

Next steps

Vision and files: send images and PDFs in messages.
Tool calling: let the model call your functions.
Structured outputs: constrain answers to a JSON schema.
Fallbacks: try another model when one fails, with a route.