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:

export OPENROUTER_API_KEY="sk-or-..."

Core Operations

Chat Completions (Single Request)

Send a single chat completion request:

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:

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:

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):

{"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:

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:

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:

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

As JSON:

python skills/openrouter/scripts/list_models.py \
  --output-format json

Get Generation Statistics

Retrieve detailed token counts and costs for a generation:

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

Bulk generation stats:

python skills/openrouter/scripts/get_generation.py \
  --generation-ids-file generation_ids.txt

Common Model Identifiers

Run list_models.py for complete list with pricing.

Output Format

All scripts return:

{
  "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.