Skip to main content

​
Overview

The @standardagents/openrouter package provides the OpenRouter provider factory for Standard Agents. OpenRouter is a multi-provider gateway that routes requests to various LLM providers (OpenAI, Anthropic, Google, Meta, and more) through a single API.

Key Features

  • Access to 200+ models from multiple providers
  • Automatic pricing data fetched from OpenRouter API
  • Typed providerOptions for routing configuration
  • Provider selection, fallbacks, and price limits
  • Zero Data Retention (ZDR) endpoints

​
Installation

npm
npm install @standardagents/openrouter
pnpm
pnpm add @standardagents/openrouter
yarn
yarn add @standardagents/openrouter

​
Quick Start

agents/models/claude_sonnet.ts
import { defineModel } from '@standardagents/spec';
import { openrouter } from '@standardagents/openrouter';

export default defineModel({
  name: 'claude-sonnet',
  provider: openrouter,
  model: 'anthropic/claude-sonnet-4',
});
OpenRouter models automatically fetch pricing from the OpenRouter API. You do not need to specify inputPrice or outputPrice.

​
Provider Factory

The openrouter export is a provider factory function: 
import { openrouter } from '@standardagents/openrouter';

defineModel({
  name: 'my-model',
  provider: openrouter,  // Pass the factory, not a string
  model: 'anthropic/claude-sonnet-4',
});

​
Model ID Format

OpenRouter uses a provider/model-name format for model IDs:
ProviderExample Model ID
OpenAIopenai/gpt-4o
Anthropicanthropic/claude-sonnet-4
Googlegoogle/gemini-2.0-flash-exp
Metameta-llama/llama-3.3-70b-instruct
Mistralmistral/mistral-large
Coherecohere/command-r-plus
Browse all available models at openrouter.ai/models.

​
Provider Options

The openrouter factory includes a typed schema for routing configuration: 
import { defineModel } from '@standardagents/spec';
import { openrouter } from '@standardagents/openrouter';

export default defineModel({
  name: 'claude-secure',
  provider: openrouter,
  model: 'anthropic/claude-sonnet-4',
  providerOptions: {
    provider: {
      zdr: true,  // Zero Data Retention
      only: ['anthropic'],  // Only route to Anthropic
      max_price: {
        prompt: 5,  // Max $5 per million input tokens
        completion: 25,  // Max $25 per million output tokens
      },
    },
  },
});

​
Routing Options

All routing options are nested under the provider key:
OptionTypeDescription
orderstring[]Provider slugs to try in order
allow_fallbacksbooleanAllow fallback to other providers (default: true)
require_parametersbooleanOnly use providers that support all request parameters
data_collection'allow' | 'deny'Control data storage policies
zdrbooleanRestrict to Zero Data Retention endpoints
onlystring[]Restrict to these providers only
ignorestring[]Skip these providers
sortstring | objectSort by price, throughput, or latency
max_priceobjectMaximum price constraints
quantizationsstring[]Allowed quantization levels
preferred_min_throughputnumber | objectMinimum throughput preference
preferred_max_latencynumber | objectMaximum latency preference

​
Price Limits

Set hard limits on pricing (request fails if no provider meets threshold): 
providerOptions: {
  provider: {
    max_price: {
      prompt: 1,        // Max $1 per million input tokens
      completion: 5,    // Max $5 per million output tokens
      request: 0.01,    // Max $0.01 per request
      image: 0.05,      // Max $0.05 per image
    },
  },
}

​
Provider Selection

Control which providers handle your requests: 
// Only use specific providers
providerOptions: {
  provider: {
    only: ['anthropic', 'openai'],
  },
}

// Prefer certain providers in order
providerOptions: {
  provider: {
    order: ['anthropic', 'openai', 'google'],
    allow_fallbacks: true,
  },
}

// Exclude specific providers
providerOptions: {
  provider: {
    ignore: ['azure'],
  },
}

​
Sorting

Sort available providers by different criteria: 
// Sort by price (cheapest first)
providerOptions: {
  provider: {
    sort: 'price',
  },
}

// Sort by throughput (fastest first)
providerOptions: {
  provider: {
    sort: 'throughput',
  },
}

// Advanced sorting with partition
providerOptions: {
  provider: {
    sort: {
      by: 'latency',
      partition: 'model',
    },
  },
}

​
Zero Data Retention (ZDR)

For sensitive data, restrict to ZDR endpoints: 
providerOptions: {
  provider: {
    zdr: true,  // Only use providers with Zero Data Retention
  },
}

​
Performance Preferences

Set soft preferences for throughput and latency: 
providerOptions: {
  provider: {
    // Simple: apply to p50 percentile
    preferred_min_throughput: 100,  // 100 tokens/sec minimum
    preferred_max_latency: 1,       // 1 second max latency

    // Advanced: specify percentiles
    preferred_min_throughput: {
      p50: 100,
      p90: 50,
    },
    preferred_max_latency: {
      p50: 0.5,
      p99: 2,
    },
  },
}

​
Type Safety

The providerOptions type is automatically inferred: 
import { openrouter } from '@standardagents/openrouter';
import type { OpenRouterProviderOptions } from '@standardagents/openrouter';

const options: OpenRouterProviderOptions = {
  provider: {
    zdr: true,
    only: ['anthropic'],
    // invalid: true,  // Error: Object literal may only specify known properties
  },
};

​
Model Capabilities

Set capabilities for proper framework behavior: 
export default defineModel({
  name: 'claude-sonnet',
  provider: openrouter,
  model: 'anthropic/claude-sonnet-4',
  capabilities: {
    supportsImages: true,
    supportsToolCalls: true,
    supportsStreaming: true,
    maxContextTokens: 200000,
  },
});

​
Environment Setup

Set your OpenRouter API key:
.dev.vars
OPENROUTER_API_KEY=sk-or-...
For Cloudflare Workers: 
wrangler secret put OPENROUTER_API_KEY

​
Example Configurations

​
Budget-Conscious Model

import { defineModel } from '@standardagents/spec';
import { openrouter } from '@standardagents/openrouter';

export default defineModel({
  name: 'budget-llm',
  provider: openrouter,
  model: 'meta-llama/llama-3.3-70b-instruct',
  providerOptions: {
    provider: {
      sort: 'price',
      max_price: {
        prompt: 0.5,
        completion: 1,
      },
    },
  },
});

​
High-Security Configuration

export default defineModel({
  name: 'secure-claude',
  provider: openrouter,
  model: 'anthropic/claude-sonnet-4',
  providerOptions: {
    provider: {
      zdr: true,
      only: ['anthropic'],
      data_collection: 'deny',
    },
  },
  capabilities: {
    supportsImages: true,
    supportsToolCalls: true,
    maxContextTokens: 200000,
  },
});

​
Multi-Provider Fallback

export default defineModel({
  name: 'resilient-model',
  provider: openrouter,
  model: 'openai/gpt-4o',
  providerOptions: {
    provider: {
      order: ['openai', 'azure', 'anthropic'],
      allow_fallbacks: true,
    },
  },
});

​
Performance-Optimized

export default defineModel({
  name: 'fast-model',
  provider: openrouter,
  model: 'anthropic/claude-sonnet-4',
  providerOptions: {
    provider: {
      sort: 'throughput',
      preferred_min_throughput: 100,
      preferred_max_latency: 0.5,
    },
  },
});

​
Generation Metadata

OpenRouter provides additional metadata about request routing that can be fetched after completion: 
import { fetchGenerationMetadata } from '@standardagents/openrouter';

const metadata = await fetchGenerationMetadata(generationId, apiKey);
// Returns: provider used, tokens, latency, etc.

​
Exports

import {
  // Provider factory
  openrouter,

  // Provider options schema (Zod)
  openrouterProviderOptions,

  // Provider class (advanced usage)
  OpenRouterProvider,

  // Metadata utilities
  fetchGenerationMetadata,
} from '@standardagents/openrouter';

import type {
  // TypeScript types
  OpenRouterProviderOptions,
  OpenRouterConfig,
  GenerationMetadata,
} from '@standardagents/openrouter';

​
Next Steps

Models

Learn about model configuration

OpenAI Provider

Direct OpenAI API access

Prompts

Configure prompts with models

defineModel API

Complete API reference