--- title: "Gateway quickstart" subtitle: "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 In the [platform](https://platform.respan.ai), 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 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: ```bash export RESPAN_API_KEY="your-respan-api-key" ``` 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](/docs/ai-gateway/spend/credits-vs-byok). - **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](/docs/ai-gateway/spend/credits-vs-byok#byok). {/* REVIEW: confirm the fee policy for credit-funded and BYOK calls before launch (no markup or fee is stated here). */} Set the base URL to the gateway's and use your Respan API key. The rest of your code stays the same. ```bash 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](/docs/ai-gateway/requests/anthropic-messages) and [Gemini](/docs/ai-gateway/requests/gemini). For a framework or coding agent, find it in [Integrations](/docs/integrations/gateway/overview). 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 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](#from-api-respan-ai) | Base URL and paths. Your key, models, saved provider keys, and Respan params carry over; fallbacks move to routes. | | [OpenAI](#from-openai) | Base URL and key. | | [Anthropic](#from-anthropic) | Base URL and key. | | [OpenRouter](#from-openrouter) | Base URL, key, model IDs, and fallbacks (to routes). | | [Vercel AI Gateway](#from-vercel-ai-gateway) | Base URL, key, model IDs, and fallbacks (to routes). | | [LiteLLM](#from-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](/docs/ai-gateway/routing/routes-and-aliases) 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`. {/* REVIEW: confirm the api.respan.ai gateway cutover timeline (deprecation and shutdown dates) before launch. */} ### 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](/docs/ai-gateway/spend/credits-vs-byok#byok). See [Chat Completions](/docs/ai-gateway/requests/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](/docs/ai-gateway/requests/anthropic-messages) and the [Claude Code guide](/docs/integrations/gateway/claude-code). ### From OpenRouter Change the base URL and key, then the model IDs. Move your fallback list into a [route](/docs/ai-gateway/routing/routes-and-aliases) 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](https://www.respan.ai/models) 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`. {/* REVIEW: confirm whether the gateway also accepts OpenRouter-style vendor/model IDs (openai/gpt-5.5) as aliases. */} | OpenRouter | Gateway | |---|---| | `models: [...]` fallback list | A [fallback route](/docs/ai-gateway/routing/fallbacks#fallback-routes) | | `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](/docs/ai-gateway/routing/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](/docs/ai-gateway/routing/fallbacks#fallback-routes). See the [Vercel AI SDK guide](/docs/integrations/gateway/vercel-ai-sdk). ### From LiteLLM If you run the LiteLLM proxy, point your clients at the gateway instead. Your routing config moves to [routes](/docs/ai-gateway/routing/routes-and-aliases) 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](/docs/ai-gateway/routing/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](/docs/integrations/gateway/lite-llm). ## 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](/docs/ai-gateway/modalities/text) | Images, video, speech, transcription, embeddings, realtime sessions, and Span-02 decisions, with the same key. | | [Routing and fallbacks](/docs/ai-gateway/routing/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](/docs/ai-gateway/spend/credits-vs-byok#byok) | Run on your provider keys, on Respan credits, or both. | | [Budgets and limits](/docs/ai-gateway/spend/budgets-and-limits) | Cap spend and requests per key, per customer, or with limit policies. | | [Logs](/docs/ai-gateway/observability/logs-and-traces) | Every call is logged with its model, provider, tokens, latency, and cost. | ## How a request flows 1. **Authenticate.** Your Respan API key is checked for the **Gateway** permission. A bad key gets `403`. 2. **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. 3. **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. 4. **Call and translate.** The request goes to the provider in its own format, and the answer comes back in yours, streamed or not. 5. **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](/docs/oss-gateway/introduction), 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](/docs/ai-gateway/customers/respan-params). - Keep working when a provider fails: [Fallbacks](/docs/ai-gateway/routing/fallbacks) with a route. - Stream responses: [Streaming](/docs/ai-gateway/requests/chat-completions#streaming). - Generate [images, audio, video, and embeddings](/docs/ai-gateway/modalities/text) with the same key.