/v1/models
List Models
Retrieve a comprehensive list of available AI models with their specifications
Overview
The List Models endpoint provides real-time information about all available models, including their capabilities, context windows, pricing, and current availability status. This helps you dynamically select the best model for your use case.
Dynamic Discovery
Discover new models as they become available
Filter & Sort
Filter models by capability, provider, or price
Real-time Status
Check model availability and performance metrics
Request
curl https://api.parrotrouter.com/v1/models \
-H "Authorization: Bearer YOUR_API_KEY"
Query Parameters
include_capabilities
Include detailed capability information for each model. Default: false
provider
Filter by provider (e.g., "openai", "anthropic", "google")
capability
Filter by capability (e.g., "chat", "completion", "image", "embedding")
active_only
Only return currently active/available models. Default: true
curl "https://api.parrotrouter.com/v1/models?provider=openai&capability=chat&include_capabilities=true" \
-H "Authorization: Bearer YOUR_API_KEY"
Response
{
"object": "list",
"data": [
{
"id": "gpt-4",
"object": "model",
"created": 1687882411,
"owned_by": "openai",
"provider": {
"id": "openai",
"name": "OpenAI"
},
"pricing": {
"prompt": 0.03,
"completion": 0.06,
"unit": "1k_tokens"
},
"context_length": 8192,
"max_tokens": 4096,
"capabilities": {
"chat": true,
"completion": true,
"function_calling": true,
"vision": false,
"embeddings": false,
"json_mode": true
},
"performance": {
"avg_response_time": 2.3,
"avg_tokens_per_second": 45,
"uptime_percentage": 99.9
},
"status": {
"active": true,
"message": "Operational"
}
},
{
"id": "claude-3-opus-20240229",
"object": "model",
"created": 1709251200,
"owned_by": "anthropic",
"provider": {
"id": "anthropic",
"name": "Anthropic"
},
"pricing": {
"prompt": 0.015,
"completion": 0.075,
"unit": "1k_tokens"
},
"context_length": 200000,
"max_tokens": 4096,
"capabilities": {
"chat": true,
"completion": true,
"function_calling": true,
"vision": true,
"embeddings": false,
"json_mode": false
},
"performance": {
"avg_response_time": 3.1,
"avg_tokens_per_second": 38,
"uptime_percentage": 99.8
},
"status": {
"active": true,
"message": "Operational"
}
}
]
}
Response Fields
id
Unique identifier for the model (use this in API requests)
provider
Information about the model provider
pricing
Cost per 1,000 tokens for prompts and completions
context_length
Maximum number of tokens the model can process
capabilities
Supported features and functionality
performance
Real-time performance metrics
status
Current availability and operational status
Code Examples
from openai import OpenAI
client = OpenAI(
base_url="https://api.parrotrouter.com/v1",
api_key="YOUR_API_KEY"
)
# List all available models
models = client.models.list()
for model in models.data:
print(f"Model: {model.id}")
print(f" Provider: {model.provider['name']}")
print(f" Context: {model.context_length} tokens")
print(f" Price: $" + str(model.pricing['prompt']) + "/1k prompt tokens")
print(f" Status: {model.status['message']}\n")
import requests
headers = {
"Authorization": "Bearer YOUR_API_KEY"
}
# Get only chat models from OpenAI
response = requests.get(
"https://api.parrotrouter.com/v1/models",
headers=headers,
params={
"provider": "openai",
"capability": "chat",
"include_capabilities": True
}
)
models = response.json()['data']
# Find models with function calling
function_calling_models = [
model for model in models
if model['capabilities'].get('function_calling', False)
]
print(f"Found {len(function_calling_models)} models with function calling")
def select_best_model(models, requirements):
"""Select the best model based on requirements"""
suitable_models = []
for model in models['data']:
# Check if model meets requirements
if model['context_length'] < requirements['min_context']:
continue
if not all(model['capabilities'].get(cap, False)
for cap in requirements['required_capabilities']):
continue
if not model['status']['active']:
continue
# Calculate score based on price and performance
price_score = 1 / (model['pricing']['prompt'] +
model['pricing']['completion'])
perf_score = model['performance']['avg_tokens_per_second']
suitable_models.append({
'model': model,
'score': price_score * perf_score
})
# Sort by score and return best
suitable_models.sort(key=lambda x: x['score'], reverse=True)
return suitable_models[0]['model'] if suitable_models else None
# Example usage
requirements = {
'min_context': 8000,
'required_capabilities': ['chat', 'function_calling'],
'max_price_per_1k': 0.05
}
best_model = select_best_model(models, requirements)
print(f"Selected model: {best_model['id']}")
Common Use Cases
Dynamic Model Selection
Select the best model based on current availability and requirements:
async def get_optimal_model(task_type):
models = await client.models.list()
if task_type == "code_generation":
# Prefer models good at coding
candidates = [m for m in models.data
if 'code' in m.id.lower() or 'gpt-4' in m.id]
elif task_type == "vision":
# Need vision capabilities
candidates = [m for m in models.data
if m.capabilities.get('vision', False)]
else:
# General chat models
candidates = [m for m in models.data
if m.capabilities.get('chat', False)]
# Sort by performance/price ratio
candidates.sort(
key=lambda m: m.performance['avg_tokens_per_second'] / m.pricing['prompt'],
reverse=True
)
return candidates[0].id if candidates else "gpt-3.5-turbo"
Fallback Strategy
Implement automatic fallback when primary model is unavailable:
class ModelFallbackStrategy {
private modelTiers = [
['gpt-4', 'claude-3-opus'],
['gpt-3.5-turbo', 'claude-3-sonnet'],
['gpt-3.5-turbo-0125']
];
async getAvailableModel(): Promise<string> {
const models = await this.fetchModels();
const activeModels = new Set(
models.filter(m => m.status.active).map(m => m.id)
);
for (const tier of this.modelTiers) {
for (const modelId of tier) {
if (activeModels.has(modelId)) {
return modelId;
}
}
}
throw new Error('No available models found');
}
}
Cost Optimization
Monitor and switch models based on pricing changes:
class CostOptimizer:
def __init__(self, budget_per_1k_tokens=0.05):
self.budget = budget_per_1k_tokens
self.model_cache = {}
async def get_cheapest_capable_model(self, required_capabilities):
models = await self.fetch_models()
eligible = [
m for m in models
if all(m['capabilities'].get(cap) for cap in required_capabilities)
and m['status']['active']
and m['pricing']['prompt'] <= self.budget
]
if not eligible:
raise ValueError("No models within budget")
# Return cheapest option
return min(eligible, key=lambda m: m['pricing']['prompt'])['id']
Best Practices
Cache Model List
Cache the model list for 5-10 minutes to reduce API calls and improve performance
Handle Unavailable Models
Always check the status field and have fallback options ready
Monitor Performance Metrics
Use performance data to optimize model selection for your use case
Version Awareness
Be aware that model IDs may include version numbers that change over time