SuperAPI AI Directory

openrouter-free

General & other

View repository

Updated 10-16 09:58

About this skill

openrouter-free

Integrate OpenRouter's free AI models with dynamic discovery, local caching, and fallback routing.


Trigger

User invokes /openrouter-free [command] [args] or asks to "list free models", "chat with a free model", or "check OpenRouter status".


Process

  1. Environment Check: Ensure OPENROUTER_API_KEY is set. If missing, show setup instructions and stop.
  2. Initialization: If first run or init command, fetch all models from GET https://openrouter.ai/api/v1/models.
  3. Caching:
    • Store models in ~/.opencode/openrouter-model-cache.json.
    • Use 0o600 permissions.
    • Respect CACHE_TTL_MS (default 1h).
  4. Filtering & Discovery:
    • Filter for models containing :free or specific capability tags.
    • Map short aliases (e.g., r1, qwen, gemma) to full IDs from references/discovery.md.
  5. Execution:
    • Discovery: List models with models [filter].
    • Interactive: Start REPL with use <model|alias>.
    • One-shot: Execute single message with chat "<msg>" [--model <id>].
    • Health: Ping models with health [model] to report latency.
  6. Resilience:
    • On 429/5xx, retry with exponential backoff (1s, 2s, 4s).
    • On model failure during use or chat, fallback to the next best model using fallback-router.ts.

Output

  • CLI Listings: Tabular or list format for models and health status.
  • Chat: Streaming SSE response for interactive and one-shot modes.
  • Cache File: Updated openrouter-model-cache.json on refresh or TTL expiry.
  • Errors: Graceful exit messages with fix suggestions for common API/Config errors.

Error Handling

Error Fix
Missing API key export OPENROUTER_API_KEY="sk-or-v1-..."
429 Rate Limit Exponential backoff, then notify user.
Model 404/503 Fallback to next best model in registry.
Cache Expired Auto-refresh from API.

Token Efficiency Rules

  • Use openrouter-free models free to list available models before suggesting one.
  • Prefer openrouter-free health over individual pings for bulk status.
  • Cache results locally to avoid redundant API calls.
  • Limit model display to OPENROUTER_MAX_DISPLAY (default 30).

Open-Weight Model Rules

  • Strict Command Syntax: Always use the defined CLI commands; do not hallucinate flags.
  • Model IDs: Use full provider/model strings (e.g., google/gemma-2-9b-it:free) unless an alias is confirmed.
  • Streaming: Ensure --stream (if applicable) or default streaming behavior is respected for long outputs.
  • Environment: Do not modify .env files directly unless instructed; guide the user to set variables.

Boundaries

  • Does not manage paid OpenRouter models unless explicitly requested.
  • Does not store user chat history beyond the current REPL session.
  • Does not modify any project files outside of ~/.opencode/ cache.

Usage Examples

# Discover all free models with vision support
openrouter-free models vision

# Chat with the longest-context free model
openrouter-free use best-free

# One-shot with a specific alias
openrouter-free chat "Write a Python HTTP server" --model r1

# Check which free models are responsive
openrouter-free health