openrouter-models

What this skill does

# OpenRouter Models

Discover, search, and compare the 300+ AI models available on OpenRouter. Query live data including pricing, context lengths, per-provider latency and uptime, throughput, supported modalities, and supported parameters.

## Prerequisites

The `OPENROUTER_API_KEY` environment variable is optional for most scripts. It is only required for `get-endpoints.ts` (provider performance data). Get a key at https://openrouter.ai/keys

## First-Time Setup

```bash
cd <skill-path>/scripts && npm install
```

## Decision Tree

Pick the right script based on what the user is asking:

| User wants to... | Script | Example |
|---|---|---|
| See all available models | `list-models.ts` | "What models does OpenRouter have?" |
| Find recently added models | `list-models.ts --sort newest` | "What are the newest models?" |
| Find cheapest models | `list-models.ts --sort price` | "What's the cheapest model?" |
| Find highest throughput models | `list-models.ts --sort throughput` | "Which models have the most output capacity?" |
| Find models in a category | `list-models.ts --category X` | "Best programming models?" |
| Search by name | `search-models.ts "query"` | "Do they have Claude?" |
| Resolve an informal model name | `resolve-model.ts "query"` | "Use the nano banana 2.0 model" |
| Find image-capable models | `search-models.ts --modality image` | "Which models accept images?" |
| Compare specific models | `compare-models.ts A B` | "Compare Claude vs GPT-4o" |
| Compare by throughput | `compare-models.ts A B --sort throughput` | "Which has higher throughput, Claude or GPT-4o?" |
| Check provider performance | `get-endpoints.ts "model-id"` | "Which provider is fastest for Claude?" |
| Find fastest provider | `get-endpoints.ts "model-id" --sort throughput` | "Fastest provider for Claude Sonnet?" |
| Find lowest-latency provider | `get-endpoints.ts "model-id" --sort latency` | "Lowest latency provider for GPT-4o?" |
| Check model availability | `get-endpoints.ts "model-id"` | "Is Claude Sonnet 4 up right now?" |

## Resolve Model

Resolve an informal or vague model name to an exact OpenRouter model ID using fuzzy matching:

```bash
cd <skill-path>/scripts && npx tsx resolve-model.ts "claude sonnet"
cd <skill-path>/scripts && npx tsx resolve-model.ts "gpt 4o mini"
cd <skill-path>/scripts && npx tsx resolve-model.ts "llama 3.1"
```

Results include a `confidence` level and `score`:

| Confidence | Score | Action |
|---|---|---|
| `high` (≥0.85) | Use the model directly — the match is unambiguous |
| `medium` (≥0.55) | Confirm with the user before proceeding |
| `low` (≥0.30) | Suggest the matches and ask the user to clarify |

**Two-step workflow:** First resolve the informal name with `resolve-model.ts`, then feed the resolved `id` into other scripts (`compare-models.ts`, `get-endpoints.ts`, etc.).

## List Models

```bash
cd <skill-path>/scripts && npx tsx list-models.ts
```

### Filter by Category

Server-side category filtering:

```bash
cd <skill-path>/scripts && npx tsx list-models.ts --category programming
```

Categories: `programming`, `roleplay`, `marketing`, `marketing/seo`, `technology`, `science`, `translation`, `legal`, `finance`, `health`, `trivia`, `academia`

### Sort Results

```bash
cd <skill-path>/scripts && npx tsx list-models.ts --sort newest      # Recently added first
cd <skill-path>/scripts && npx tsx list-models.ts --sort price       # Cheapest first
cd <skill-path>/scripts && npx tsx list-models.ts --sort context     # Largest context first
cd <skill-path>/scripts && npx tsx list-models.ts --sort throughput  # Most output tokens first
```

Models with upcoming `expiration_date` values trigger a stderr warning.

## Search Models

```bash
cd <skill-path>/scripts && npx tsx search-models.ts "claude"
cd <skill-path>/scripts && npx tsx search-models.ts --modality image
cd <skill-path>/scripts && npx tsx search-models.ts "gpt" --modality text
```

Modalities: `text`, `image`, `audio`, `file`

## Compare Models

Compare two or more models side-by-side with pricing in per-million-tokens format. Uses exact ID matching — `openai/gpt-4o` matches only that model, not variants like `gpt-4o-mini`.

```bash
cd <skill-path>/scripts && npx tsx compare-models.ts "anthropic/claude-sonnet-4" "openai/gpt-4o"
cd <skill-path>/scripts && npx tsx compare-models.ts "anthropic/claude-sonnet-4" "openai/gpt-4o" "google/gemini-2.5-pro" --sort price
```

Sort options: `price` (cheapest first), `context` (largest first), `speed`/`throughput` (most output tokens first)

## Provider Performance (Endpoints)

Get per-provider latency, uptime, and throughput for any model:

```bash
cd <skill-path>/scripts && npx tsx get-endpoints.ts "anthropic/claude-sonnet-4"
cd <skill-path>/scripts && npx tsx get-endpoints.ts "anthropic/claude-sonnet-4" --sort throughput
cd <skill-path>/scripts && npx tsx get-endpoints.ts "openai/gpt-4o" --sort latency
```

Sort options: `throughput` (fastest tokens/sec first), `latency` (lowest p50 ms first), `uptime` (most reliable first), `price` (cheapest first)

Returns for each provider:
- **Latency** (p50/p75/p90/p99 in ms) — median to worst-case response times
- **Throughput** (p50/p75/p90/p99 tokens/sec) — generation speed
- **Uptime** — percentage over the last 30 minutes
- **Status** — `operational` or `degraded`
- **Provider-specific pricing** — some providers offer discounts
- **Supported parameters** — varies by provider (some don't support all features)

## API Response Shapes

`GET /api/v1/models` returns `{ data: Model[] }`. For full field reference, see the [Models reference](https://openrouter.ai/docs/guides/overview/models).

**Query parameters** (all optional):

| Parameter | Example | Effect |
|---|---|---|
| `category` | `?category=programming` | Server-side category filter |
| `supported_parameters` | `?supported_parameters=tools` | Only models supporting this parameter |

**Tips for working with the response:**

- To check if a model supports a feature, use `model.supported_parameters` (e.g. `.includes("tools")`), or filter server-side with `?supported_parameters=tools`.
- To check modalities, use `model.architecture.input_modalities` / `model.architecture.output_modalities`.
- Pricing values are per-token in USD as strings — multiply by 1,000,000 for per-million-token pricing.
- `knowledge_cutoff` and `expiration_date` are date strings or null.
- `links.details` points to the per-provider endpoints API for that model. `GET /api/v1/models/{author}/{slug}/endpoints` returns `{ data: { id, name, endpoints: Endpoint[] } }`.
- Endpoint `status`: `0` = operational, non-zero = degraded.
- Endpoint `latency_last_30m` / `throughput_last_30m`: percentile objects with `p50`, `p75`, `p90`, `p99`.

## Script Output Formats

The scripts below reformat the raw API data. When calling the API directly (e.g. via `fetch`), refer to the [OpenAPI spec](https://openrouter.ai/openapi.json) for field names.

### list-models.ts / search-models.ts

A subset of the raw API fields — the scripts run `formatModel()` which drops `canonical_slug`, `hugging_face_id`, `default_parameters`, `knowledge_cutoff`, and `links`. If you need those fields, call the API directly.

### compare-models.ts

```json
{
  "id": "anthropic/claude-sonnet-4",
  "name": "Anthropic: Claude Sonnet 4",
  "context_length": 1000000,
  "max_completion_tokens": 64000,
  "per_request_limits": null,
  "pricing_per_million_tokens": {
    "prompt": "$3.00",
    "completion": "$15.00",
    "cached_input": "$0.30"
  },
  "modalities": { "input": ["text", "image"], "output": ["text"] },
  "supported_parameters": ["max_tokens", "temperature", "..."],
  "is_moderated": false
}
```

### get-endpoints.ts

```json
{
  "model_id": "anthropic/claude-sonnet-4",
  "model_name": "Anthropic: Claude Sonnet 4",
  "total_providers": 5,
  "endpoints": [
    {
      "provider": "Anthropic",
      "tag": "anthropic",
      "status": "operational",
      "uptime_30m": "100.00%",
      "latency_30m_ms":