Skip to content
zidane
SDK reference

zidane/providers/openrouter

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

import { … } from 'zidane/providers/openrouter'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.

TypeScript
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#

normalizeOpenRouterModelIdFunction#

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

TypeScript
function normalizeOpenRouterModelId(modelId: string): string

Parameters

Parameters
NameTypeDescription
modelIdstring

Model id as stored or requested.

Returns

string

src/providers/openrouter.ts:89

openrouterFunction#

OpenRouter provider.

Thin wrapper around openaiCompat with OpenRouter-specific defaults (base URL, default model) and required attribution headers.

TypeScript
function openrouter(params?: OpenRouterParams): Provider

Parameters

Parameters
NameTypeDescription
params?OpenRouterParams

API key, default model, capabilities, PDF engine and prompt-cache key settings.

Returns

Provider

Example

Example
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.' })

src/providers/openrouter.ts:111

Constants#

OPENROUTER_DEFAULT_MODELConstant#

Model the OpenRouter provider uses when none is configured.

TypeScript
const OPENROUTER_DEFAULT_MODEL = 'anthropic/claude-opus-5.5'

src/providers/openrouter.ts:9

Interfaces#

OpenRouterParamsInterface#

Options for openrouter.

TypeScript
interface OpenRouterParams

Properties

OpenRouterParams properties
NameTypeDefaultDescription
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'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.

src/providers/openrouter.ts:23