> ## Documentation Index
> Fetch the complete documentation index at: https://bifrost-dev.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenRouter

> OpenRouter API conversion guide - routing to multiple providers, reasoning support, parameter handling, and streaming

## Overview

OpenRouter is an **OpenAI-compatible provider routing service** that accesses models from multiple providers (OpenAI, Anthropic, Google, Meta, etc.) through a unified interface. Bifrost delegates to the OpenAI implementation with special handling for reasoning models. Key features:

* **Provider aggregation** - Access 100+ models from multiple vendors
* **Reasoning support** - Extended thinking for supported models
* **Parameter compatibility** - Intelligent reasoning effort conversion
* **Streaming support** - Full SSE support with usage tracking
* **Tool calling** - Complete function definition and execution

### Supported Operations

| Operation            | Non-Streaming | Streaming | Endpoint                   |
| -------------------- | ------------- | --------- | -------------------------- |
| Chat Completions     | ✅             | ✅         | `/v1/chat/completions`     |
| Responses API        | ✅             | ✅         | `/v1/responses`            |
| Text Completions     | ✅             | ✅         | `/v1/completions`          |
| List Models          | ✅             | -         | `/v1/models`               |
| Embeddings           | ✅             | -         | `/v1/embeddings`           |
| Speech (TTS)         | ✅             | ❌         | `/v1/audio/speech`         |
| Transcriptions (STT) | ✅             | ❌         | `/v1/audio/transcriptions` |
| Image Generation     | ❌             | ❌         | -                          |
| Files                | ❌             | ❌         | -                          |
| Batch                | ❌             | ❌         | -                          |

<Note>
  **Unsupported Operations** (❌): Image Generation, Files, Batch, and streaming Speech/Transcriptions are not supported by the upstream OpenRouter API. These return a `BifrostError` with an error code of `"unsupported_operation"`.

  **Note**: OpenRouter's Responses API is currently in **beta**.
</Note>

## Setup & Configuration

Configure OpenRouter as a provider.

<Tabs>
  <Tab title="Web UI">
    <img src="https://mintcdn.com/bifrost-dev/9w_pm34AEj2nak5O/media/provider-dashboard-openrouter.png?fit=max&auto=format&n=9w_pm34AEj2nak5O&q=85&s=a6aecbc6713207843b5114270b3a43c9" alt="OpenRouter provider dashboard" width="2048" height="1152" data-path="media/provider-dashboard-openrouter.png" />

    1. Navigate to **Models** > **Model Providers**. Look for **OpenRouter** under **Configured Providers**. If it is missing, click on **Add New Provider** and select **OpenRouter**.
    2. Click **Add Key** or edit an existing key.
    3. Set a name for your key.
    4. Paste your API key directly or use an environment variable (for example, `env.OPENROUTER_API_KEY`).
    5. Set **Allowed Models** to **All Models** (default) or the specific model allowlist you want this key to serve.
    6. Save the provider configuration.
  </Tab>

  <Tab title="config.json">
    ```json theme={null}
    {
      "providers": {
        "openrouter": {
          "keys": [
            {
              "name": "openrouter-key-1",
              "value": "env.OPENROUTER_API_KEY",
              "models": [
                "*"
              ],
              "weight": 1.0
            }
          ]
        }
      }
    }
    ```
  </Tab>

  <Tab title="API">
    Refer to the API documentation for [Provider Keys Management](https://docs.getbifrost.ai/api-reference/providers/create-a-key-for-a-provider).
  </Tab>

  <Tab title="Go SDK">
    ```go theme={null}
    case schemas.OpenRouter:
        return []schemas.Key{{
            Name:   "openrouter-key-1",
            Value:  *schemas.NewSecretVar("env.OPENROUTER_API_KEY"),
            Models: []string{"*"},
            Weight: 1.0,
        }}, nil
    ```
  </Tab>
</Tabs>

OpenRouter key validation uses `/v1/auth/key` when provider key validation is enabled.

***

# 1. Chat Completions

## Request Parameters

OpenRouter supports all standard OpenAI chat completion parameters. For full parameter reference and behavior, see [OpenAI Chat Completions](/providers/supported-providers/openai#1-chat-completions).

### Reasoning Parameter Handling

OpenRouter supports extended thinking on compatible models:

```json theme={null}
// Bifrost request
{
  "reasoning": {
    "effort": "high",
    "max_tokens": 10000
  }
}

// OpenRouter conversion
{
  "reasoning_effort": "high"
}
```

**Reasoning Models:** gpt-oss-120b and compatible models with special handling for reasoning content.

### Cache Control Stripping

Anthropic-specific cache control directives are automatically removed:

```go theme={null}
// Bifrost supports cache control from Anthropic
{
  "messages": [{
    "role": "user",
    "content": [{
      "type": "text",
      "text": "...",
      "cache_control": {"type": "ephemeral"}  // ← Stripped
    }]
  }]
}

// Sent to OpenRouter without cache directives
```

### Filtered Parameters

Removed for OpenRouter compatibility:

* `prompt_cache_key` - Not supported
* `verbosity` - Anthropic-specific
* `store` - Not supported
* `service_tier` - OpenAI-specific

OpenRouter supports all standard OpenAI message types, tools, responses, and streaming formats. For details on message handling, tool conversion, responses, and streaming, refer to [OpenAI Chat Completions](/providers/supported-providers/openai#1-chat-completions).

***

# 2. Responses API

OpenRouter's Responses API is handled as a distinct endpoint at `/v1/responses`. This API is currently in **beta** on OpenRouter.

Same parameter support as Chat Completions, with requests forwarded directly to the Responses API endpoint without conversion to Chat Completions.

**Special Message Handling (gpt-oss vs other models):**
For details on how reasoning is handled differently between gpt-oss and other models, see [OpenAI Responses API documentation](/providers/supported-providers/openai) for the comprehensive explanation of reasoning conversion (summaries vs. content blocks).

***

# 3. Text Completions

OpenRouter supports legacy text completion format:

| Parameter              | Mapping             |
| ---------------------- | ------------------- |
| `prompt`               | Direct pass-through |
| `max_tokens`           | max\_tokens         |
| `temperature`, `top_p` | Direct pass-through |
| `stop`                 | Stop sequences      |

***

# 4. List Models

Lists 100+ models available through OpenRouter, including:

* OpenAI (GPT-4, GPT-4 Turbo, etc.)
* Anthropic (Claude 3 family)
* Google (Gemini)
* Meta (Llama)
* Mistral
* And many more

***

# 5. Embeddings

OpenRouter supports embeddings through their OpenAI-compatible API. This allows you to generate vector embeddings for text using models from various providers.

| Parameter         | Mapping                                                                          |
| ----------------- | -------------------------------------------------------------------------------- |
| `input`           | Direct pass-through (string or array of strings)                                 |
| `model`           | Model ID (e.g., `cohere/embed-multilingual-v3.0`, `amazon/amazon-embeddings-v2`) |
| `dimensions`      | Number of dimensions for the output embedding                                    |
| `encoding_format` | Output format (`float` or `base64`)                                              |

**Supported Models:** OpenRouter supports various embedding models including:

* Cohere (embed-multilingual-v3.0, embed-english-v3.0, etc.)
* Amazon (amazon-embeddings-v2)
* And other providers

The embedding request/response follows the standard OpenAI format.

***

## Speech (TTS) & Transcription (STT)

<Info>Speech and Transcription support for OpenRouter is available in **Bifrost v2.0.0 and above**.</Info>

OpenRouter exposes OpenAI-compatible audio endpoints, so Bifrost routes Speech and Transcription requests the same way it does for OpenAI: `/v1/audio/speech` for text-to-speech and `/v1/audio/transcriptions` for speech-to-text.

| Parameter         | Mapping                                                                                      |
| ----------------- | -------------------------------------------------------------------------------------------- |
| `model`           | TTS/STT model ID (e.g., `openai/gpt-4o-mini-tts`, `openai/whisper-1`)                        |
| `voice`           | Required for Speech; voice availability depends on the underlying model                      |
| `response_format` | Speech: `mp3` or `pcm` (`pcm` if omitted). Transcription: `json` (default) or `verbose_json` |
| `speed`           | Optional playback speed multiplier for Speech (provider-dependent)                           |
| `language`        | Optional ISO-639-1 code for Transcription; auto-detected if omitted                          |

Streaming Speech and Transcription are not supported by the upstream OpenRouter API and return a `BifrostError` with `"unsupported_operation"`.

***

## Unsupported Features

| Feature                     | Reason                        |
| --------------------------- | ----------------------------- |
| Image Generation            | Not offered by OpenRouter API |
| Streaming Speech/TTS        | Not offered by OpenRouter API |
| Streaming Transcription/STT | Not offered by OpenRouter API |
| Batch Operations            | Not offered by OpenRouter API |
| File Management             | Not offered by OpenRouter API |

***

## Caveats

<Accordion title="Cache Control Stripped">
  **Severity**: Medium
  **Behavior**: Anthropic cache control directives are removed
  **Impact**: Prompt caching features unavailable
  **Code**: Stripped during JSON marshaling
</Accordion>

<Accordion title="Parameter Filtering">
  **Severity**: Low
  **Behavior**: OpenAI-specific parameters filtered
  **Impact**: prompt\_cache\_key, verbosity, store removed
  **Code**: filterOpenAISpecificParameters
</Accordion>

<Accordion title="User Field Size Limit">
  **Severity**: Low
  **Behavior**: User field > 64 characters silently dropped
  **Impact**: Longer user identifiers are lost
  **Code**: SanitizeUserField enforces 64-char max
</Accordion>