# zidane/providers/openrouter

> The OpenRouter provider, one API key for models from many vendors.

Import: `import { … } from 'zidane/providers/openrouter'`. Source: [src/providers/openrouter.ts](https://github.com/Tahul/zidane/blob/main/src/providers/openrouter.ts).

Use `openrouter()` to reach models from several vendors through one account. It reads `OPENROUTER_API_KEY` when you pass no key. It sends prompt-cache breakpoints, which the Anthropic and Gemini routes honor. Set `promptCacheKey` (for example `'session'`) to send a cache-affinity key. Model ids use the `vendor/model` form, and `normalizeOpenRouterModelId()` maps legacy ids to their current slugs.

```ts
import { createAgent } from 'zidane'
import { openrouter } from 'zidane/providers/openrouter'

const agent = createAgent({ provider: openrouter({ defaultModel: 'anthropic/claude-fable-5.1' }) })
const stats = await agent.run({ prompt: 'Summarize README.md in three bullets.' })
console.log(stats.turns)
```

## Functions

### `normalizeOpenRouterModelId`

Function.

Maps legacy OpenRouter model ids to their current slugs and returns other ids unchanged.

```ts
function normalizeOpenRouterModelId(modelId: string): string
```

**Parameters**

- `modelId` (`string`): Model id as stored or requested.

**Returns** `string`

Source: [src/providers/openrouter.ts:89](https://github.com/Tahul/zidane/blob/main/src/providers/openrouter.ts#L89)

### `openrouter`

Function.

OpenRouter provider.

Thin wrapper around [`openaiCompat`](https://zidane.si/docs/reference/providers-openai-compat.md#openaiCompat) with OpenRouter-specific defaults
(base URL, default model) and required attribution headers.

```ts
function openrouter(params?: OpenRouterParams): Provider
```

**Parameters**

- `params?` (`OpenRouterParams`): API key, default model, capabilities, PDF engine and prompt-cache key settings.

**Returns** `Provider`

**Example**

```ts
import { createAgent } from 'zidane'
import { openrouter } from 'zidane/providers/openrouter'

const agent = createAgent({
  provider: openrouter({ apiKey: process.env.OPENROUTER_API_KEY }),
})
await agent.run({ prompt: 'Say hello.' })
```

Source: [src/providers/openrouter.ts:111](https://github.com/Tahul/zidane/blob/main/src/providers/openrouter.ts#L111)

## Constants

### `OPENROUTER_DEFAULT_MODEL`

Constant.

Model the OpenRouter provider uses when none is configured.

```ts
const OPENROUTER_DEFAULT_MODEL = 'anthropic/claude-opus-5.5'
```

Source: [src/providers/openrouter.ts:9](https://github.com/Tahul/zidane/blob/main/src/providers/openrouter.ts#L9)

## Interfaces

### `OpenRouterParams`

Interface.

Options for [`openrouter`](https://zidane.si/docs/reference/providers-openrouter.md#openrouter).

```ts
interface OpenRouterParams
```

**Properties**

- `apiKey?` (`string`): API key. Falls back to the `OPENROUTER_API_KEY` environment variable.
- `capabilities?` (`ProviderCapabilities`): Provider capability flags. OpenRouter itself is a router — whether vision,
  native image-in-tool-result, or document/PDF input are supported depends on
  the downstream model. Default: `{ vision: true, imageInToolResult: false,
  documents: true }` — matches the default `anthropic/claude-opus-5.5` model
  (vision + PDF capable; OpenRouter forwards the OpenAI `file` content part to
  Anthropic/OpenAI/Gemini routes).

  Override when routing to a known-text-only model (e.g. `meta-llama/llama-3-8b-instruct`),
  setting the relevant flags to `false`.
- `defaultModel?` (`string`, default `'anthropic/claude-opus-5.5'`): Model used when a request does not set one.
- `pdfEngine?` (`'native' | 'pdf-text' | 'mistral-ocr'`): PDF-parsing engine for OpenRouter's `file-parser` plugin. Applied only when
  a request carries a forwarded PDF/`file` part. Default `'pdf-text'` (free
  text-only extraction, safe on any downstream model). Set `'native'` to use
  the downstream model's own file support, or `'mistral-ocr'` for
  scanned/image PDFs. See `OpenAICompatParams.pdfEngine`.
- `promptCacheKey?` (`PromptCacheKeyOption`): Prompt-cache affinity key, sent as `prompt_cache_key`. Off by default.

  OpenRouter reads this field as its sticky-routing key, so enabling it pins a
  session's turns to the provider endpoint that already holds its cache —
  complementing the automatic stickiness it applies after a cached request.
  `'session'` keys on the agent's session id. See `./prompt-cache-key.ts`.
- `promptCacheKeyHeader?` (`string`): Additionally send the affinity key as this HTTP header, for gateways in
  front of OpenRouter that route on a header rather than a body field.

Source: [src/providers/openrouter.ts:23](https://github.com/Tahul/zidane/blob/main/src/providers/openrouter.ts#L23)