openrouter-models

name	openrouter-models
description	Expert guidance for querying and searching OpenRouter models. Use when fetching available AI models, filtering models by capabilities, comparing model pricing, or integrating OpenRouter's model API.

What is OpenRouter?

OpenRouter provides unified access to 300+ AI models through a single API endpoint. It aggregates models from various providers (OpenAI, Anthropic, Google, Cohere, etc.) and makes them available through a standardized API.

When to Use OpenRouter Models API

• Fetching available models and their capabilities
• Filtering models by output modalities (text, image, audio, embeddings)
• Finding models that support specific parameters (tools, function calling)
• Comparing pricing across different models
• Checking model context windows and limits
• Building model selection interfaces
• Implementing dynamic model switching

API Endpoint

Base URL

https://openrouter.ai/api/v1/models

Authentication

OpenRouter API requires an API key in the Authorization header:

curl -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  "https://openrouter.ai/api/v1/models"

Query Parameters

output_modalities

Filter models by their output capabilities. Accepts comma-separated values or "all".

Value	Description
text	Models that produce text output (default)
image	Models that generate images
audio	Models that produce audio output
embeddings	Embedding models
all	Include all models, skip modality filtering

Examples:

# Default — text models only
curl "https://openrouter.ai/api/v1/models"

# Image generation models only
curl "https://openrouter.ai/api/v1/models?output_modalities=image"

# Text and image models
curl "https://openrouter.ai/api/v1/models?output_modalities=text,image"

# All models regardless of modality
curl "https://openrouter.ai/api/v1/models?output_modalities=all"

supported_parameters

Filter models by the API parameters they support.

Examples:

# Models that support tool calling
curl "https://openrouter.ai/api/v1/models?supported_parameters=tools"

# Models that support structured outputs
curl "https://openrouter.ai/api/v1/models?supported_parameters=structured_outputs"

# Models that support reasoning
curl "https://openrouter.ai/api/v1/models?supported_parameters=reasoning"

API Response Schema

Root Response Object

{
  "data": [
    /* Array of Model objects */
  ]
}

Model Object Schema

Field	Type	Description
id	string	Unique model identifier (e.g., "google/gemini-2.5-pro-preview")
canonical_slug	string	Permanent slug that never changes
name	string	Human-readable display name
created	number	Unix timestamp when model was added to OpenRouter
description	string	Description of model's capabilities
context_length	number	Maximum context window size in tokens
architecture	Architecture	Technical capabilities object
pricing	Pricing	Lowest price structure for this model
top_provider	TopProvider	Primary provider configuration
per_request_limits	Rate limiting info (null if no limits)
supported_parameters	string[]	Array of supported API parameters
default_parameters	object | null	Default parameter values (null if none)
expiration_date	string | null	Deprecation date (null if not deprecated)

Architecture Object

{
  "input_modalities": string[],  // ["file", "image", "text"]
  "output_modalities": string[], // ["text", "image", "audio"]
  "tokenizer": string,          // Tokenization method
  "instruct_type": string | null // Instruction format
}

Pricing Object

All values in USD per token/request/unit. "0" means free.

{
  "prompt": string,              // Cost per input token
  "completion": string,          // Cost per output token
  "request": string,             // Fixed cost per API request
  "image": string,               // Cost per image input
  "web_search": string,          // Cost per web search
  "internal_reasoning": string,  // Cost for reasoning tokens
  "input_cache_read": string,    // Cost per cached input read
  "input_cache_write": string    // Cost per cached input write
}

Top Provider Object

{
  "context_length": number,        // Provider-specific context limit
  "max_completion_tokens": number, // Max tokens in response
  "is_moderated": boolean         // Whether content moderation is applied
}

Supported Parameters

Array indicating which OpenAI-compatible parameters work:

• tools - Function calling
• tool_choice - Tool selection control
• max_tokens - Response length limiting
• temperature - Randomness control
• top_p - Nucleus sampling
• reasoning - Internal reasoning mode
• include_reasoning - Include reasoning in response
• structured_outputs - JSON schema enforcement
• response_format - Output format specification
• stop - Custom stop sequences
• frequency_penalty - Repetition reduction
• presence_penalty - Topic diversity
• seed - Deterministic outputs

Script Examples

Fetch All Models (Node.js)

async function fetchAllModels(apiKey) {
  const response = await fetch('https://openrouter.ai/api/v1/models', {
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'HTTP-Referer': 'https://your-site.com',
      'X-Title': 'Your App Name'
    }
  });
  
  const data = await response.json();
  return data.data;
}

// Usage
const models = await fetchAllModels(process.env.OPENROUTER_API_KEY);
console.log(`Found ${models.length} models`);

Fetch Text Models Only (Node.js)

async function fetchTextModels(apiKey) {
  const response = await fetch(
    'https://openrouter.ai/api/v1/models?output_modalities=text',
    {
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'HTTP-Referer': 'https://your-site.com',
        'X-Title': 'Your App Name'
      }
    }
  );
  
  const data = await response.json();
  return data.data;
}

Fetch Models with Tool Support (Node.js)

async function fetchModelsWithTools(apiKey) {
  const response = await fetch(
    'https://openrouter.ai/api/v1/models?supported_parameters=tools',
    {
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'HTTP-Referer': 'https://your-site.com',
        'X-Title': 'Your App Name'
      }
    }
  );
  
  const data = await response.json();
  return data.data;
}

Fetch All Models (Python)

import requests

def fetch_all_models(api_key):
    headers = {
        'Authorization': f'Bearer {api_key}',
        'HTTP-Referer': 'https://your-site.com',
        'X-Title': 'Your App Name'
    }
    
    response = requests.get(
        'https://openrouter.ai/api/v1/models',
        headers=headers
    )
    
    return response.json()['data']

# Usage
import os
models = fetch_all_models(os.environ.get('OPENROUTER_API_KEY'))
print(f"Found {len(models)} models")

Filter Models by Context Window (Node.js)

function filterByContextWindow(models, minContext) {
  return models.filter(model => 
    model.context_length >= minContext
  );
}

// Usage
const models = await fetchAllModels(apiKey);
const largeContextModels = filterByContextWindow(models, 100000);
console.log(`Models with 100k+ context: ${largeContextModels.length}`);

Find Cheapest Model (Node.js)

function findCheapestModel(models, modality = 'text') {
  return models.reduce((cheapest, model) => {
    const price = parseFloat(model.pricing.prompt);
    const cheapestPrice = parseFloat(cheapest.pricing.prompt);
    return price < cheapestPrice ? model : cheapest;
  });
}

// Usage
const models = await fetchAllModels(apiKey);
const cheapest = findCheapestModel(models);
console.log(`Cheapest model: ${cheapest.name} ($${cheapest.pricing.prompt}/1k tokens)`);

Search Models by Name (Node.js)

function searchModelsByName(models, query) {
  const lowerQuery = query.toLowerCase();
  return models.filter(model => 
    model.name.toLowerCase().includes(lowerQuery) ||
    model.id.toLowerCase().includes(lowerQuery)
  );
}

// Usage
const models = await fetchAllModels(apiKey);
const gptModels = searchModelsByName(models, 'gpt');
console.log(`Found ${gptModels.length} GPT models`);

Compare Model Pricing (Node.js)

function comparePricing(models) {
  return models.map(model => ({
    name: model.name,
    id: model.id,
    promptPrice: model.pricing.prompt,
    completionPrice: model.pricing.completion,
    context: model.context_length
  })).sort((a, b) => 
    parseFloat(a.promptPrice) - parseFloat(b.promptPrice)
  );
}

// Usage
const models = await fetchAllModels(apiKey);
const pricingComparison = comparePricing(models);
console.table(pricingComparison);

Advanced Queries

Multiple Filters

# Text models with tool support
curl "https://openrouter.ai/api/v1/models?output_modalities=text&supported_parameters=tools"

# Image models with specific parameters
curl "https://openrouter.ai/api/v1/models?output_modalities=image&supported_parameters=max_tokens"

RSS Feed

Subscribe to model updates via RSS:

curl "https://openrouter.ai/api/v1/models?use_rss=true"

Model Count Endpoint

Get count of models matching filters:

curl "https://openrouter.ai/api/v1/models/count"
curl "https://openrouter.ai/api/v1/models/count?output_modalities=text"

Best Practices

API Key Security

• Never commit API keys to version control
• Use environment variables
• Rotate keys regularly
• Monitor usage for unusual patterns

Rate Limiting

• Implement client-side rate limiting
• Cache model lists (they don't change frequently)
• Use appropriate backoff on errors
• Monitor per-request limits

Error Handling

• Handle network errors gracefully
• Implement retry logic with exponential backoff
• Validate API responses
• Log errors for debugging

Performance

• Cache model lists for 5-15 minutes
• Use streaming for large responses
• Implement pagination if needed
• Filter on server side when possible

Tokenization Note

Different models tokenize text differently:

• GPT, Claude, Llama: Multi-character tokens
• PaLM: Character-level tokenization
• Token counts (and costs) vary between models
• Use the usage field in API responses for actual token counts

Common Use Cases

Building a Model Selector

async function buildModelSelector(apiKey) {
  const models = await fetchAllModels(apiKey);
  
  return {
    text: models.filter(m => m.architecture.output_modalities.includes('text')),
    image: models.filter(m => m.architecture.output_modalities.includes('image')),
    tools: models.filter(m => m.supported_parameters.includes('tools')),
    cheap: models.filter(m => parseFloat(m.pricing.prompt) < 0.001),
    largeContext: models.filter(m => m.context_length > 100000)
  };
}

Dynamic Model Selection

function selectBestModel(models, requirements) {
  return models.filter(model => {
    if (requirements.tools && !model.supported_parameters.includes('tools')) {
      return false;
    }
    if (requirements.minContext && model.context_length < requirements.minContext) {
      return false;
    }
    if (requirements.maxPrice && parseFloat(model.pricing.prompt) > requirements.maxPrice) {
      return false;
    }
    return true;
  }).sort((a, b) => 
    parseFloat(a.pricing.prompt) - parseFloat(b.pricing.prompt)
  )[0];
}

Model Comparison Table

function createComparisonTable(models) {
  return models.map(model => ({
    Name: model.name,
    Context: model.context_length,
    Prompt: model.pricing.prompt,
    Completion: model.pricing.completion,
    Tools: model.supported_parameters.includes('tools') ? 'Yes' : 'No',
    Reasoning: model.supported_parameters.includes('reasoning') ? 'Yes' : 'No'
  }));
}

Additional Endpoints

Website Model Browser

Explore models interactively:

https://openrouter.ai/models

Documentation

• Models API: https://openrouter.ai/docs/api-reference/models/get-models
• Model Count: https://openrouter.ai/docs/api-reference/models/count
• Overview: https://openrouter.ai/docs/guides/overview/models

Community

• Discord: https://openrouter.ai/discord
• Provider inquiries: https://openrouter.ai/docs/guides/get-started/for-providers