> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pipecat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenRouter LLM

> OpenRouterLLMService reaches OpenRouter's multi-provider model catalog through an OpenAI-compatible streaming interface.

## Overview

`OpenRouterLLMService` provides access to OpenRouter's language models through an OpenAI-compatible interface. It inherits from `OpenAILLMService` and supports streaming responses, function calling, and context management with access to multiple model providers through a single API.

> [card] [OpenRouter LLM API Reference](https://reference-server.pipecat.ai/en/latest/api/pipecat.services.openrouter.llm.html)
>
> Pipecat's API methods for OpenRouter integration

> [card] [Example Implementation](https://github.com/pipecat-ai/pipecat/blob/main/examples/function-calling/function-calling-openrouter.py)
>
> Complete example with function calling

> [card] [OpenRouter Documentation](https://openrouter.ai/docs/api-reference/chat-completion)
>
> Official OpenRouter API documentation and features

> [card] [OpenRouter Platform](https://openrouter.ai/)
>
> Access multiple model providers and manage API keys

## Installation

To use OpenRouter services, install the required dependencies:

```bash theme={null}
uv add "pipecat-ai[openrouter]"
```

## Prerequisites

### OpenRouter Account Setup

Before using OpenRouter LLM services, you need:

1. **OpenRouter Account**: Sign up at [OpenRouter](https://openrouter.ai/)
2. **API Key**: Generate an API key from your account dashboard
3. **Model Selection**: Choose from hundreds of available models from different providers
4. **Credits**: Add credits to your account for model usage

### Required Environment Variables

* `OPENROUTER_API_KEY`: Your OpenRouter API key for authentication

## Configuration

**api\_key** `str` *required*

OpenRouter API key for authentication. Raises `ValueError` when empty.

**model** `str` *deprecated* (default: None)

*Deprecated since 0.0.105, removed in 2.0.0.* Use
`settings=OpenRouterLLMService.Settings(model=...)` instead.

**settings** `OpenRouterLLMService.Settings` (default: None)

Runtime-configurable settings. See [Settings](#settings) below.

**base\_url** `str` (default: [https://openrouter.ai/api/v1](https://openrouter.ai/api/v1))

Base URL for OpenRouter API endpoint.

### Settings

Runtime-configurable settings passed via the `settings` constructor argument using `OpenRouterLLMService.Settings(...)`. These can be updated mid-conversation with `LLMUpdateSettingsFrame`. See [Service Settings](https://docs.pipecat.ai/pipecat/fundamentals/service-settings.md) for details.

This service extends `OpenAILLMService.Settings` with OpenRouter-specific parameters:

**provider** `OpenRouterProviderPreferences | dict | None` (default: None)

Which upstream providers may serve the request. Controls OpenRouter's provider
routing preferences — which providers may serve a request, in what order, and
under what latency, throughput, price, quantization, and data-retention
constraints. Accepts an `OpenRouterProviderPreferences` instance or a plain
dict (coerced to `OpenRouterProviderPreferences`). When unset or `None`,
OpenRouter routes by its default order. See [Provider
Routing](#provider-routing) below for the full field reference.

For all other settings (model, temperature, max\_completion\_tokens, etc.), see [OpenAI LLM Settings](https://docs.pipecat.ai/api-reference/server/services/llm/openai.md#settings).

## Usage

### Basic Setup

```python theme={null}
import os
from pipecat.services.openrouter.llm import OpenRouterLLMService

llm = OpenRouterLLMService(
    api_key=os.getenv("OPENROUTER_API_KEY"),
    settings=OpenRouterLLMService.Settings(
        model="openai/gpt-4.1",  # Default model
    ),
)
```

### With a Different Provider Model

```python theme={null}
from pipecat.services.openrouter.llm import OpenRouterLLMService

llm = OpenRouterLLMService(
    api_key=os.getenv("OPENROUTER_API_KEY"),
    settings=OpenRouterLLMService.Settings(
        model="anthropic/claude-sonnet-4",
        temperature=0.7,
        max_completion_tokens=1024,
    ),
)
```

### With Provider Routing Preferences

```python theme={null}
from pipecat.services.openrouter.llm import OpenRouterLLMService

# Optimize for latency
llm = OpenRouterLLMService(
    api_key=os.getenv("OPENROUTER_API_KEY"),
    settings=OpenRouterLLMService.Settings(
        model="openai/gpt-4.1",
        provider={"sort": "latency"},
    ),
)

# Route to specific providers only
llm = OpenRouterLLMService(
    api_key=os.getenv("OPENROUTER_API_KEY"),
    settings=OpenRouterLLMService.Settings(
        model="openai/gpt-4.1",
        provider={"only": ["azure"], "allow_fallbacks": False},
    ),
)

# Set throughput and latency constraints
llm = OpenRouterLLMService(
    api_key=os.getenv("OPENROUTER_API_KEY"),
    settings=OpenRouterLLMService.Settings(
        model="openai/gpt-4.1",
        provider={
            "preferred_min_throughput": {"p90": 50},
            "preferred_max_latency": {"p90": 1.5},
        },
    ),
)
```

## Provider Routing

OpenRouter can route requests to multiple upstream providers for each model. The `provider` parameter in `Settings` controls these routing preferences.

### OpenRouterProviderPreferences Fields

| Parameter | Type | Default | Description |
| - | - | - | - |
| `order` | `list[str]` | `None` | Provider slugs to try, in order, before any others. Turns off load balancing. |
| `allow_fallbacks` | `bool` | `None` | Whether to fall back to providers outside `order`, `only`, and `quantizations`. `None` leaves OpenRouter's default, `True`. |
| `require_parameters` | `bool` | `None` | Route only to providers supporting every parameter in the request. `None` leaves OpenRouter's default, `False`. |
| `data_collection` | `"allow" \| "deny"` | `None` | `"deny"` restricts to providers that do not collect user data. `None` leaves OpenRouter's default, `"allow"`. |
| `zdr` | `bool` | `None` | Route only to zero-data-retention endpoints. |
| `enforce_distillable_text` | `bool` | `None` | Route only to models that allow text distillation. |
| `only` | `list[str]` | `None` | Provider slugs to route to, excluding all others. |
| `ignore` | `list[str]` | `None` | Provider slugs never to route to. |
| `quantizations` | `list[str]` | `None` | Quantization levels to accept, e.g. `["fp8", "bf16"]`. |
| `sort` | `"price" \| "throughput" \| "latency" \| dict` | `None` | Attribute to rank providers by, or an object `{"by": ..., "partition": "model" \| "none"}`. Turns off load balancing. |
| `preferred_min_throughput` | `float \| dict` | `None` | Throughput in tokens/sec below which a provider is deprioritized. Number or percentile thresholds (`"p50"`, `"p75"`, `"p90"`, `"p99"`). |
| `preferred_max_latency` | `float \| dict` | `None` | Latency in seconds above which a provider is deprioritized. Number or percentile thresholds (`"p50"`, `"p75"`, `"p90"`, `"p99"`). |
| `max_price` | `dict` | `None` | Cost ceilings in USD: `"prompt"` and `"completion"` per million tokens, `"request"` per request, `"image"` per image. |

For provider slugs and full routing semantics, see [OpenRouter's provider selection guide](https://openrouter.ai/docs/guides/routing/provider-selection).

## Notes

* OpenRouter model identifiers use the `provider/model` format (e.g., `openai/gpt-4o`, `anthropic/claude-sonnet-4`, `google/gemini-2.5-pro`).
* The default model is `openai/gpt-4.1`.
* **Developer message conversion**: OpenRouter requests convert `developer` messages to `user` messages by default. To use models that support the `developer` role, set `llm.supports_developer_role = True` after instantiation or subclass `OpenRouterLLMService` to override this behavior.
* When using Gemini models through OpenRouter, the service automatically handles the constraint that only one system message is allowed by converting additional system messages to user messages.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.