GET
/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

Basic Requestbash
curl https://api.parrotrouter.com/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

Query Parameters

include_capabilities
optional
boolean

Include detailed capability information for each model. Default: false

provider
optional
string

Filter by provider (e.g., "openai", "anthropic", "google")

capability
optional
string

Filter by capability (e.g., "chat", "completion", "image", "embedding")

active_only
optional
boolean

Only return currently active/available models. Default: true

Request with Filtersbash
curl "https://api.parrotrouter.com/v1/models?provider=openai&capability=chat&include_capabilities=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

Response Structurejson
{
  "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

List All Modelspython
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")
Filter Modelspython
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")
Model Selection Logicpython
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

Related Topics