# Openrouter

> Unified API access to hundreds of AI models through OpenRouter. Use when agents need to send chat completions to any LLM (GPT-4, Claude, Llama, Mistral, etc.), process bulk prompts at scale, list available models, or retrieve generation statistics and costs. Key operations include chat completions (single and bulk), model listing, and generation stats retrieval. Supports streaming, function calling, structured JSON output, and comprehensive token/cost tracking.

- Skill: `buzzmatic/openrouter` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add buzzmatic/openrouter`
- Raw SKILL.md: https://api.skillmd.com/api/skills/buzzmatic/openrouter/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: Buzzmatic (https://skillmd.com/u/buzzmatic)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/buzzmatic/openrouter

---


# OpenRouter API Skill

Access hundreds of AI models through a single unified API.

## Quick Start

All scripts:
- Accept an optional `--output-dir` parameter (default: `output/`)
- Save raw JSON and processed data to that directory
- Return JSON with `{"output_files": [...], "summary": "..."}`

## Environment Setup

Set the required environment variable:
```bash
export OPENROUTER_API_KEY="sk-or-..."
```

## Core Operations

### Chat Completions (Single Request)

Send a single chat completion request:

```bash
python skills/openrouter/scripts/chat.py \
  --model "anthropic/claude-3-opus" \
  --messages '[{"role":"user","content":"Summarize the benefits of SEO"}]' \
  --max-tokens 500 \
  --temperature 0.7
```

**With system prompt:**
```bash
python skills/openrouter/scripts/chat.py \
  --model "openai/gpt-4" \
  --messages '[{"role":"system","content":"You are an SEO expert"},{"role":"user","content":"Explain keyword clustering"}]' \
  --max-tokens 1000
```

### Chat Completions (Bulk Mode)

Process multiple prompts from a JSONL file:

```bash
python skills/openrouter/scripts/chat.py \
  --model "openai/gpt-4-turbo" \
  --messages-file data/processed/prompts.jsonl \
  --max-tokens 500 \
  --batch-size 10 \
  --rate-limit 60
```

**JSONL format** (one request per line):
```json
{"messages":[{"role":"user","content":"Analyze keyword: seo tools"}],"id":"kw_001"}
{"messages":[{"role":"user","content":"Analyze keyword: backlink checker"}],"id":"kw_002"}
```

**With tools/function calling:**
```bash
python skills/openrouter/scripts/chat.py \
  --model "openai/gpt-4-turbo" \
  --messages '[{"role":"user","content":"Get weather for Berlin"}]' \
  --tools-file tools.json \
  --tool-choice auto
```

**With structured JSON output:**
```bash
python skills/openrouter/scripts/chat.py \
  --model "openai/gpt-4-turbo" \
  --messages '[{"role":"user","content":"Extract entities from: Apple released iPhone 15"}]' \
  --response-format '{"type":"json_schema","json_schema":{"name":"entities","schema":{"type":"object","properties":{"entities":{"type":"array"}}}}}'
```

### List Available Models

Fetch and cache available models:

```bash
python skills/openrouter/scripts/list_models.py \
  --output-format csv
```

**As JSON:**
```bash
python skills/openrouter/scripts/list_models.py \
  --output-format json
```

### Get Generation Statistics

Retrieve detailed token counts and costs for a generation:

```bash
python skills/openrouter/scripts/get_generation.py \
  --generation-id "gen-xxxxx"
```

**Bulk generation stats:**
```bash
python skills/openrouter/scripts/get_generation.py \
  --generation-ids-file generation_ids.txt
```

## Common Model Identifiers

| Provider | Model ID | Context | Best For |
|----------|----------|---------|----------|
| OpenAI | `openai/gpt-4-turbo` | 128k | Complex reasoning |
| OpenAI | `openai/gpt-4o` | 128k | Fast, multimodal |
| Anthropic | `anthropic/claude-3-opus` | 200k | Long-form content |
| Anthropic | `anthropic/claude-3-sonnet` | 200k | Balanced speed/quality |
| Meta | `meta-llama/llama-3-70b-instruct` | 8k | Open source, fast |
| Mistral | `mistral/mistral-large` | 32k | European compliance |
| Google | `google/gemini-pro-1.5` | 1M | Ultra-long context |

Run `list_models.py` for complete list with pricing.

## Output Format

All scripts return:

```json
{
  "output_files": [
    "output/raw/openrouter_responses_{timestamp}.json",
    "output/processed/openrouter_results_{timestamp}.csv"
  ],
  "summary": "Processed 50 requests: 48 success, 2 errors. Total: 125,430 tokens, $0.42",
  "stats": {
    "success_count": 48,
    "error_count": 2,
    "total_tokens": 125430,
    "prompt_tokens": 45000,
    "completion_tokens": 80430,
    "total_cost": 0.42,
    "model_used": "openai/gpt-4-turbo"
  }
}
```

## Rate Limits and Best Practices

- **Default rate limit:** 60 requests/minute (adjustable via `--rate-limit`)
- **Batch size:** Default 10 concurrent requests (adjustable via `--batch-size`)
- **Retries:** Automatic exponential backoff for 429 errors
- **Cost tracking:** All responses include token counts and estimated costs

For detailed API parameters, see [references/api_reference.md](references/api_reference.md).