Gateway quickstart

One API and one key for every model. Send your first request in five minutes, or move over from another gateway.

The Respan gateway is one endpoint, https://gateway.respan.ai, for models from OpenAI, Anthropic, Google, and many more providers. Point the SDK you already use at it and pass your Respan API key. Your code stays the same, and every call shows up in Logs with its cost.

You need a Respan account and either Respan credits or your own provider key.

Set up with your coding agent

Paste this prompt into Claude Code, Cursor, Codex, or any coding agent:


Help me set up the Respan gateway: fetch and follow https://www.respan.ai/docs/ai-gateway/quickstart.md

To do it yourself, follow the steps below.

Step by step

Create an API key

In the platform , go to Gateway › API keys and click New key. Keep Gateway checked, pick Production or Test, and click Create.

The Create new key dialog with Name, Environment (Production or Test), and Permissions: Read, Write, Gateway, and Admin

Click Copy, then Done. You won’t see the key again, so save it now:

Terminal


export RESPAN_API_KEY="your-respan-api-key"

Choose who pays the provider

Each call runs on Respan credits or on your own provider key:

Respan credits: go to Gateway › Credits and add credits. You’re charged the provider’s usage at the model’s catalog price, and a call on Respan’s key with no credits is refused. See Pricing.
Your own key: on Gateway › API keys, click Bring your own key and add your provider’s key. Calls to that provider then run on it first, and the provider bills you directly. See BYOK.

Make your first request

Set the base URL to the gateway’s and use your Respan API key. The rest of your code stays the same.

Terminal


curl -i 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": "Hello!"}]}'

Python


import os
from openai import OpenAI

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

raw = client.chat.completions.with_raw_response.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(raw.headers.get("x-respan-log-id"))
print(raw.parse().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 { data, response } = await client.chat.completions
  .create({
    model: "gpt-5.5",
    messages: [{ role: "user", content: "Hello!" }],
  })
  .withResponse();
console.log(response.headers.get("x-respan-log-id"));
console.log(data.choices[0].message.content);

The response has an X-Respan-Log-Id header: the ID of this request’s log.

Using the Anthropic SDK or the Google GenAI SDK? See Anthropic Messages and Gemini. For a framework or coding agent, find it in Integrations.

See it in Logs

Open Gateway › Logs. Your request is at the top, under the log ID from the X-Respan-Log-Id header.

Gateway Logs listing the latest requests, newest first, with time, log ID, span name, model, system, and user message

Click the row to see the full request and response, the model and provider that answered, its tokens, latency, and cost.

Migrate to Respan gateway

Already on api.respan.ai, a provider SDK, or another gateway? For most apps, moving means changing two lines: the base URL and the API key.

From	Change
api.respan.ai	Base URL and paths. Your key, models, saved provider keys, and Respan params carry over; fallbacks move to routes.
OpenAI	Base URL and key.
Anthropic	Base URL and key.
OpenRouter	Base URL, key, model IDs, and fallbacks (to routes).
Vercel AI Gateway	Base URL, key, model IDs, and fallbacks (to routes).
LiteLLM	Base URL, key, and fallbacks (to routes).

From api.respan.ai

The gateway at gateway.respan.ai replaces the one at api.respan.ai. Your Respan API key works on both, your provider keys saved in the platform keep serving your calls, and your Respan params (customer_identifier, customer_params, metadata, thread_identifier, trace_unique_id, span_name, trace_name, disable_log) carry over unchanged. Fallbacks and load balancing are configured as routes in the platform, and you send the route’s name as model.

Python


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

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

Request	api.respan.ai	gateway.respan.ai
Chat Completions	`/api/chat/completions`	`/v1/chat/completions`
Responses	`/api/responses`	`/v1/responses`
Anthropic Messages (SDK base URL)	`https://api.respan.ai/api/anthropic/`	`https://gateway.respan.ai`
Gemini (SDK base URL)	`https://api.respan.ai/api/google/gemini`	`https://gateway.respan.ai`
Embeddings	`/api/embeddings`	`/v1/embeddings`
Span decisions	`/api/v1/decisions`	`/api/v1/systemone`

Management APIs (logs, prompts, customers, routes, limit policies) stay on https://api.respan.ai.

From OpenAI

Keep the OpenAI SDK. Change the base URL and use your Respan API key. Model IDs for OpenAI models stay the same, such as gpt-5.5.

Python


# Before
client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

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

To keep paying OpenAI directly, save your OpenAI key with BYOK. See Chat Completions.

From Anthropic

Keep the Anthropic SDK. Change the base URL and use your Respan API key.

Python


# Before
client = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

# After
client = anthropic.Anthropic(base_url="https://gateway.respan.ai", api_key=os.environ["RESPAN_API_KEY"])

For Claude Code, set ANTHROPIC_BASE_URL=https://gateway.respan.ai and ANTHROPIC_API_KEY to your Respan key (and unset ANTHROPIC_AUTH_TOKEN, which Claude Code prefers when both are set). See Anthropic Messages and the Claude Code guide.

From OpenRouter

Change the base URL and key, then the model IDs. Move your fallback list into a route and send its name as model.

Python


# Before
client = OpenAI(base_url="https://openrouter.ai/api/v1", api_key=os.environ["OPENROUTER_API_KEY"])
client.chat.completions.create(
    model="openai/gpt-5.5",
    messages=messages,
    extra_body={"models": ["anthropic/claude-sonnet-4.5"]},
)

# After: "smart" is a fallback route with entries gpt-5.5, then claude-sonnet-4-5-20250929
client = OpenAI(base_url="https://gateway.respan.ai/v1", api_key=os.environ["RESPAN_API_KEY"])
client.chat.completions.create(model="smart", messages=messages)

Model IDs come from the model catalog and have no vendor prefix: gpt-5.5, not openai/gpt-5.5. To reach a model through OpenRouter itself, prefix it with openrouter/, as in openrouter/openai/gpt-oss-120b.

OpenRouter	Gateway
`models: [...]` fallback list	A fallback route
`provider.order`	A fallback route whose entries are provider offerings, such as `azure/gpt-5.5`, then `gpt-5.5`
`provider.only`	A provider offering ID such as `azure/gpt-5.5`, or the `X-Respan-Route-Provider` header on Messages, Responses, and Gemini
`provider.allow_fallbacks: false`	A provider offering ID, which keeps the request on that provider
`user`	`customer_identifier`

See Provider routing.

From Vercel AI Gateway

With the AI SDK, swap the gateway provider for the OpenAI provider pointed at Respan, and drop the vendor prefix from model IDs.

TypeScript


// Before
import { gateway } from "@ai-sdk/gateway";
const result = await generateText({ model: gateway("openai/gpt-5.5"), prompt });

// After
import { createOpenAI } from "@ai-sdk/openai";
const respan = createOpenAI({ baseURL: "https://gateway.respan.ai/v1", apiKey: process.env.RESPAN_API_KEY });
const result = await generateText({ model: respan.chat("gpt-5.5"), prompt });

Vercel’s providerOptions.gateway.order maps to a provider offering ID or a fallback route of provider offerings, and its models fallback list to a fallback route. See the Vercel AI SDK guide.

From LiteLLM

If you run the LiteLLM proxy, point your clients at the gateway instead. Your routing config moves to routes in the Respan platform.

Python


# Before
client = OpenAI(base_url="http://localhost:4000", api_key=os.environ["LITELLM_KEY"])
client.chat.completions.create(model="gpt-5.5", messages=messages, extra_body={"fallbacks": ["claude-sonnet-4-5-20250929"]})

# After: "smart" is a fallback route with entries gpt-5.5, then claude-sonnet-4-5-20250929
client = OpenAI(base_url="https://gateway.respan.ai/v1", api_key=os.environ["RESPAN_API_KEY"])
client.chat.completions.create(model="smart", messages=messages)

LiteLLM model_list entries with weights become load balancing: key weights across your saved provider keys, or a split route across models. If you call the LiteLLM SDK in-process, see the LiteLLM guide.

What you get

Feature	What it does
Any model, any format	Call any model in the OpenAI, Anthropic Messages, or Gemini format. The gateway translates between them, so switching models is a one-field change.
Multimodal	Images, video, speech, transcription, embeddings, realtime sessions, and Span-02 decisions, with the same key.
Routing and fallbacks	Routes you configure in the platform try models in order or split traffic by weight. Your own keys serve first.
Bring your own key	Run on your provider keys, on Respan credits, or both.
Budgets and limits	Cap spend and requests per key, per customer, or with limit policies.
Logs	Every call is logged with its model, provider, tokens, latency, and cost.

How a request flows

Authenticate. Your Respan API key is checked for the Gateway permission. A bad key gets 403.
Admit. Rate limits, limit policies, customer budgets, and key caps are checked before any provider is called. A request over a limit gets 402 or 429 and costs nothing.
Route. model becomes an ordered list of attempts, each one provider on one key: your keys first, then Respan’s. A failed attempt moves to the next one.
Call and translate. The request goes to the provider in its own format, and the answer comes back in yours, streamed or not.
Bill and log. A call on Respan credits is charged from the provider’s reported usage; a call on your key is billed by the provider. Each request is one trace in Logs, named by the X-Respan-Log-Id header.

The gateway runs on the open-source Respan gateway, a Rust core for request formats, provider calls, and routing. The hosted gateway adds API keys, credits, limits, routes, and logging.

Next steps

Tag requests with a customer and your own properties: Respan params.
Keep working when a provider fails: Fallbacks with a route.
Stream responses: Streaming.
Generate images, audio, video, and embeddings with the same key.