openrouter_skill

Overview

This skill is an expert OpenRouter API assistant for AI agents, providing practical guidance for integrating with OpenRouter's unified access to 400+ models. It focuses on chat completions, streaming, tool calling, structured outputs, multimodal inputs, model selection, routing, and robust error handling. Use it to build reliable, cost-effective agent integrations that require provider flexibility and advanced features.

How this skill works

The skill describes the core request and response patterns for OpenRouter's chat/completions endpoint, including required headers and minimal request structure. It explains streaming (SSE) handling, non-streaming parsing, tool-calling mechanics, structured output modes (JSON and JSON Schema), model selection and variant usage, provider routing, and error/retry strategies. Practical code snippets and parameter recommendations guide implementation choices and parameter tuning.

When to use it

• Making chat completions or agent-driven conversations across many providers
• Implementing streaming real-time responses for chat UIs or terminals
• Enabling tool/function calling and executing model-driven workflows
• Enforcing structured outputs for APIs, databases, or automated pipelines
• Routing across providers and implementing model fallbacks for reliability
• Handling multimodal inputs (images, audio, video, PDFs) and embeddings

Best practices

• Always specify model and set max_tokens to control cost and avoid runaway output
• Use streaming for low-latency user-facing UIs and non-streaming for batch or synchronous processing
• Set temperature/top_p/top_k according to task (low for code/factual, higher for creative tasks)
• Provide explicit provider order and fallbacks when reliability or cost guarantees matter
• Wrap requests with exponential backoff and graceful handling for 429/5xx errors
• Use response_format/json_schema for strict, machine-parseable outputs when integrating downstream systems

Example use cases

• A chat application that streams assistant tokens to the client with progressive UI updates
• An agent that calls external tools (search, DB, APIs) via model-invoked tool calls and executes returned arguments
• Batch document analysis using large-context variants to process and summarize multi-file uploads
• Cost-optimized routing that prefers free or low-cost variants with automatic fallbacks to paid providers on failure
• A data extraction pipeline that requires strict JSON Schema output for downstream ingestion