OpenRouter Provider for Vercel AI SDK

To use Anthropic-specific prompt caching, include providerOptions.openrouter.cacheControl within the message content objects. The provider automatically converts these to the correct format for OpenRouter.

import { createOpenRouter } from '@openrouter/ai-sdk-provider';
import { streamText } from 'ai';

const openrouter = createOpenRouter({ apiKey: 'your-api-key' });
const model = openrouter('anthropic/<supported-caching-model>');

await streamText({
  model,
  messages: [
    { role: 'system', content: 'You are a helpful assistant.' },
    {
      role: 'user',
      content: [
        { type: 'text', text: 'Given the text body below:' },
        {
          type: 'text',
          text: `<LARGE BODY OF TEXT>`,
          providerOptions: {
            openrouter: {
              cacheControl: { type: 'ephemeral' },
            },
          },
        },
        { type: 'text', text: 'List the speakers?' },
      ],
    },
  ],
});

You can track token usage and costs directly in your API responses by enabling usage accounting.

1. Enable it by passing { usage: { include: true } } to the model configuration.
2. Access standard usage via the AI SDK result.usage object (e.g., inputTokens, cacheReadTokens, reasoningTokens).
3. Access provider-specific details via result.providerMetadata?.openrouter?.usage. This includes cost and totalTokens.

This also supports BYOK (Bring Your Own Key) usage accounting, allowing you to track upstreamInferenceCost when using your own provider keys in OpenRouter.

// Enable usage accounting
const model = openrouter('openai/gpt-3.5-turbo', {
  usage: {
    include: true,
  },
});

// Access usage accounting data
const result = await generateText({
  model,
  prompt: 'Hello, how are you today?',
});

// AI SDK v7 standard usage details
console.log('Input tokens:', result.usage.inputTokens);
console.log('Cached input tokens:', result.usage.inputTokenDetails.cacheReadTokens);
console.log('Reasoning tokens:', result.usage.outputTokenDetails.reasoningTokens);

// Provider-specific usage details (available in providerMetadata)
if (result.providerMetadata?.openrouter?.usage) {
  console.log('Cost:', result.providerMetadata.openrouter.usage.cost);
  console.log(
    'Total Tokens:',
    result.providerMetadata.openrouter.usage.totalTokens,
  );
}

// For BYOK (Bring Your Own Key) scenarios:
if (result.providerMetadata?.openrouter?.usage) {
  const costDetails = result.providerMetadata.openrouter.usage.costDetails;
  if (costDetails) {
    console.log('BYOK cost:', costDetails.upstreamInferenceCost);
  }
}

There are three ways to pass additional parameters to the OpenRouter API via the extraBody property:

1. Via providerOptions.openrouter: Pass options during the AI SDK function call (e.g., streamText).
2. Via model settings: Pass options when creating the model instance using openrouter(modelId, { extraBody: ... }).
3. Via the model factory: Pass options globally when initializing the provider with createOpenRouter({ extraBody: ... }).

import { createOpenRouter } from '@openrouter/ai-sdk-provider';
import { streamText } from 'ai';

// 1. Via providerOptions
const openrouter = createOpenRouter({ apiKey: 'your-api-key' });
const model = openrouter('anthropic/claude-3.7-sonnet:thinking');
await streamText({
  model,
  messages: [{ role: 'user', content: 'Hello' }],
  providerOptions: {
    openrouter: {
      reasoning: { max_tokens: 10 },
    },
  },
});

// 2. Via model settings
const modelWithSettings = openrouter('anthropic/claude-3.7-sonnet:thinking', {
  extraBody: { reasoning: { max_tokens: 10 } },
});

// 3. Via model factory
const globalOpenRouter = createOpenRouter({
  apiKey: 'your-api-key',
  extraBody: { reasoning: { max_tokens: 10 } },
});

The OpenRouter provider exposes rich metadata through the providerMetadata field in both doGenerate and doStream responses. This allows access to provider-specific details that are not part of the standard AI SDK schema.

Metadata Structure

Inside providerMetadata.openrouter, you can access:

• provider: The name of the underlying provider.
• reasoning_details: An array of ReasoningDetailUnion objects (Text, Summary, or Encrypted) used for multi-turn roundtripping.
• usage: Detailed usage accounting including cost, promptTokensDetails.cachedTokens, and completionTokensDetails.reasoningTokens.
• annotations: File annotations (e.g., for citations or file references).

Reasoning Details

Reasoning is returned as reasoning content parts. The reasoning_details metadata is crucial for preserving the state of 'thinking' blocks (including signatures and encrypted blobs) when performing multi-turn conversations.

The OpenRouterChatLanguageModel uses OpenRouterChatSettings to configure model-level behavior. Key settings include:

• models: The specific models to use.
• logitBias: Logit bias settings.
• logprobs: Boolean or number for logprob requests.
• user: User identifier.
• parallelToolCalls: Whether to allow parallel tool calls.
• maxTokens: Maximum output tokens.
• temperature: Sampling temperature.
• topP: Nucleus sampling.
• frequencyPenalty: Penalty for frequent tokens.
• presencePenalty: Penalty for presence of tokens.
• topK: Top-K sampling.
• includeReasoning: Whether to include reasoning/thinking details.
• reasoning: Specific reasoning settings.
• usage: Whether to include usage accounting.
• plugins: Web search or other plugins.
• webSearchOptions: Configuration for web search.
• provider: Provider routing settings.
• debug: Debugging mode.
• cacheControl: Anthropic-style automatic caching.
• extraBody: Additional body parameters for the API.