> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://respan.ai/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://respan.ai/docs/_mcp/server.

# OpenRouter (gateway)

> Route OpenRouter requests through the Respan gateway.

Point OpenAI-compatible calls at the Respan gateway and use OpenRouter model names (`openrouter/openai/gpt-6-sol`, `openrouter/anthropic/claude-opus-5.5`, etc.).

## Setup

#### Install packages

**`Python`**

```bash Python
pip install openai
```

**`TypeScript`**

```bash TypeScript
npm install openai
```

#### Set environment variables

```bash
export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
```

No `OPENROUTER_API_KEY` is needed when billing/routing through Respan Gateway credits. For BYOK, configure credentials in the Respan provider settings.

#### Point client to gateway

```python
from openai import OpenAI
import os

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

response = client.chat.completions.create(
    model="openrouter/openai/gpt-6-sol",
    messages=[{"role": "user", "content": "Hello via Respan Gateway OpenRouter."}],
)
print(response.choices[0].message.content)
```

**`TypeScript`**

```typescript TypeScript
import OpenAI from "openai";

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

const response = await client.chat.completions.create({
  model: "openrouter/openai/gpt-6-sol",
  messages: [
    { role: "user", content: "Hello via Respan Gateway OpenRouter." },
  ],
});

console.log(response.choices[0].message.content);
```

#### Switch models

```python
client.chat.completions.create(model="openrouter/cohere/command-a-plus", messages=[{"role":"user","content":"Compare routing options."}])
client.chat.completions.create(model="openrouter/anthropic/claude-opus-5.5", messages=[{"role":"user","content":"Summarize routing."}])
```

**`TypeScript`**

```typescript TypeScript
await client.chat.completions.create({
  model: "openrouter/cohere/command-a-plus",
  messages: [{ role: "user", content: "Compare routing options." }],
});
await client.chat.completions.create({
  model: "openrouter/anthropic/claude-opus-5.5",
  messages: [{ role: "user", content: "Summarize routing." }],
});
```

See [OpenRouter model docs](/docs/integrations/gateway/model-providers/openrouter) for full provider/key options and routing behavior.

## Reasoning and provider routing

For `openrouter/*` models, Respan forwards OpenRouter's `reasoning` and `provider` objects to OpenRouter verbatim, so you can disable reasoning or constrain provider routing with OpenAI-compatible calls.

```python
response = client.chat.completions.create(
    model="openrouter/deepseek/deepseek-v4.1-flash",
    messages=[{"role": "user", "content": "Summarize routing."}],
    extra_body={
        "reasoning": {"enabled": False},
        "provider": {"zdr": True},
    },
)
```

Only object-shaped values are forwarded. A `reasoning` list is treated as Respan's own log field, which is the shape our logs use for a model's reasoning output, and OpenRouter rejects a list outright. Both keys are forwarded for `openrouter/*` models only.

## Native passthrough

The setup above makes OpenAI-compatible calls. Respan validates these requests against its schema and can bill through Respan gateway credits. Call the native passthrough endpoint when you need OpenRouter's control surface beyond `reasoning` and `provider`, such as `reasoning_effort: "none"`, a field OpenRouter adds later, or the `provider`, `native_finish_reason` and `reasoning_details` fields OpenRouter returns. It relays the request with no Respan schema in between.

```python
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["RESPAN_API_KEY"],
    base_url="https://api.respan.ai/api/openrouter/v1",
    default_headers={"x-openrouter-api-key": os.environ["OPENROUTER_API_KEY"]},
)

response = client.chat.completions.create(
    model="anthropic/claude-opus-5.5",
    messages=[{"role": "user", "content": "Hello via the OpenRouter passthrough."}],
    extra_body={"provider": {"order": ["anthropic"]}},
)
print(response.choices[0].message.content)
```

This endpoint is BYOK. `Authorization` carries your Respan API key and `x-openrouter-api-key` carries your OpenRouter API key. Both are required, and there is no fallback to Respan gateway credits. Use OpenRouter's own model slug rather than the `openrouter/`-prefixed form, though the prefix is also accepted. OpenRouter's response, status code, and event stream are relayed back unchanged, so an upstream `402`, `404`, or `429` reaches your client as that same status. The request is still logged in Respan.

See [Routing & passthrough](/docs/documentation/features/gateway/routing-and-passthrough) for a full comparison of the two shapes and how this sits alongside the Anthropic and Google passthroughs.