# Openrouter Integration > Connect apps to hundreds of AI models through OpenRouter — live model and discount discovery, batch and service-tier cost controls, multimodal chat, exact cost and credit diagnostics, provider routing, reasoning, tool calling, structured output validation, starter templates, production playbooks, and verification scripts. Use when an agent needs to add, compare, audit, or debug OpenRouter models, pricing, promotions, credits, routing, requests, or generated assets. - Skill: `bnishit/openrouter-integration` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add bnishit/openrouter-integration` - Raw SKILL.md: https://api.skillmd.com/api/skills/bnishit/openrouter-integration/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning - Author: bnishit (https://skillmd.com/u/bnishit) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/bnishit/openrouter-integration --- # OpenRouter Integration Use official OpenRouter docs as the source of truth for current endpoints, parameters, and capability metadata. Prefer `openrouter.ai/docs`, `openrouter.ai/openapi.json`, and the API reference pages under `openrouter.ai/docs/api-reference`. ## Quick Snippets Use these for fast copy-paste before reaching for the fuller references or templates. ### Curl: list models ```bash curl -s https://openrouter.ai/api/v1/models \ -H "Authorization: Bearer $OPENROUTER_API_KEY" \ -H "Accept: application/json" ``` ### Curl: list providers ```bash curl -s https://openrouter.ai/api/v1/providers \ -H "Authorization: Bearer $OPENROUTER_API_KEY" \ -H "Accept: application/json" ``` ### Curl: fetch one generation and its cost ```bash curl -s "https://openrouter.ai/api/v1/generation?id=$GENERATION_ID" \ -H "Authorization: Bearer $OPENROUTER_API_KEY" \ -H "Accept: application/json" ``` ### Curl: inspect key and account credit headroom ```bash curl -s https://openrouter.ai/api/v1/key \ -H "Authorization: Bearer $OPENROUTER_API_KEY" \ -H "Accept: application/json" # Requires a management key. This is account-wide, unlike /api/v1/key. curl -s https://openrouter.ai/api/v1/credits \ -H "Authorization: Bearer $OPENROUTER_MANAGEMENT_KEY" \ -H "Accept: application/json" ``` ### Fetch: free models from the catalog ```ts const res = await fetch("https://openrouter.ai/api/v1/models", { headers: { Authorization: `Bearer ${process.env.OPENROUTER_API_KEY}`, Accept: "application/json", }, }); const json = await res.json(); const freeModels = (json?.data ?? []).filter((model: any) => { const pricing = model?.pricing ?? {}; return ["prompt", "completion", "request", "image"].every((key) => { const value = pricing[key]; return value == null || value === "0"; }); }); ``` ### Curl: text-only chat call ```bash curl -s https://openrouter.ai/api/v1/chat/completions \ -H "Authorization: Bearer $OPENROUTER_API_KEY" \ -H "Content-Type: application/json" \ -H "HTTP-Referer: ${OPENROUTER_SITE_URL:-http://localhost:3000}" \ -H "X-OpenRouter-Title: ${OPENROUTER_APP_NAME:-My App}" \ -d '{ "model": "openai/gpt-4o-mini", "messages": [ {"role": "user", "content": "Write a one-line summary of invoice OCR."} ], "temperature": 0 }' ``` ### Fetch: image input ```ts const res = await fetch("https://openrouter.ai/api/v1/chat/completions", { method: "POST", headers: { Authorization: `Bearer ${process.env.OPENROUTER_API_KEY}`, "Content-Type": "application/json", "HTTP-Referer": process.env.OPENROUTER_SITE_URL || "http://localhost:3000", "X-OpenRouter-Title": process.env.OPENROUTER_APP_NAME || "My App", }, body: JSON.stringify({ model: "google/gemini-2.5-flash", messages: [ { role: "user", content: [ { type: "text", text: "Extract all visible text from this image." }, { type: "image_url", image_url: { url: imageDataUrl }, }, ], }, ], temperature: 0, }), }); const json = await res.json(); const content = json?.choices?.[0]?.message?.content; ``` ### Fetch: image generation ```ts const res = await fetch("https://openrouter.ai/api/v1/images", { method: "POST", headers: { Authorization: `Bearer ${process.env.OPENROUTER_API_KEY}`, "Content-Type": "application/json", "HTTP-Referer": process.env.OPENROUTER_SITE_URL || "http://localhost:3000", "X-OpenRouter-Title": process.env.OPENROUTER_APP_NAME || "My App", }, body: JSON.stringify({ model: "google/gemini-3.1-flash-image", prompt: "Generate a clean product-style illustration of a glass teacup on a plain background.", aspect_ratio: "1:1", resolution: "1K", output_format: "png", }), }); const json = await res.json(); const imageUrl = json?.data?.[0]?.b64_json ? `data:${json.data[0].media_type || "image/png"};base64,${json.data[0].b64_json}` : null; ``` ### Fetch: PDF input with file-parser ```ts const res = await fetch("https://openrouter.ai/api/v1/chat/completions", { method: "POST", headers: { Authorization: `Bearer ${process.env.OPENROUTER_API_KEY}`, "Content-Type": "application/json", "HTTP-Referer": process.env.OPENROUTER_SITE_URL || "http://localhost:3000", "X-OpenRouter-Title": process.env.OPENROUTER_APP_NAME || "My App", }, body: JSON.stringify({ model: "google/gemini-2.5-flash", messages: [ { role: "user", content: [ { type: "text", text: "Extract the invoice totals as JSON." }, { type: "file", file: { filename: "invoice.pdf", file_data: pdfDataUrl, }, }, ], }, ], plugins: [ { id: "file-parser", pdf: { engine: "cloudflare-ai" }, }, ], response_format: { type: "json_object" }, temperature: 0, }), }); ``` ## Workflow 1. Check the docs before making non-trivial changes. - Run `scripts/check_openrouter_docs.py --quick` when accuracy matters or the integration seems stale. - If the script flags warnings, read `references/docs-check-workflow.md` and browse only the flagged official pages. - Reconcile templates, headers, and parameter usage with the current docs before coding. 2. Keep secrets server-side. - Do not expose `OPENROUTER_API_KEY` in browser code. - Put a server route in front of OpenRouter for model discovery and chat calls. - Set `HTTP-Referer` and `X-OpenRouter-Title` headers when the app has a stable URL and title. - Do not forward arbitrary user-supplied `http(s)` asset URLs straight to OpenRouter. Fetch trusted assets server-side and convert them to `data:` URLs, or enforce an explicit host allowlist such as `OPENROUTER_ALLOWED_REMOTE_ASSET_HOSTS`. 3. Install a starter instead of retyping boilerplate. - Use `scripts/install_template.sh` with `--template nextjs` or `--template express`. - Override base path and env var names at install time when the target project already has conventions. - Copy shared helpers, streaming UI example, and test fixtures with the template. 4. Decide what you are integrating. - Catalog, providers, free-model filters, key/credit diagnostics, or generation cost lookup: read `references/catalogs-and-costs.md`. - Promotions, discounted endpoints, workload cost comparisons, batch, or service tiers: read `references/discounts-and-cost-controls.md`. - Model catalog or picker: read `references/models-and-ui.md`. - Model selection, provider filters, or fallback policy that should be production-friendly: read `references/catalog-routing-best-practices.md`. - Text, image analysis, dedicated image generation, or PDF inference: read `references/requests-and-responses.md`. - End-to-end image asset workflows such as icons, OG images, preview, and storage: read `references/image-generation-best-practices.md`. - Tool calling or an agentic loop: read `references/tools-and-function-calling.md`. - Tool reliability or structured-output extraction that should survive production use: read `references/tool-calling-and-structured-output-best-practices.md`. - Routing and failover policy: read `references/routing-and-fallbacks.md`. - Logging, generation audit, and cost observability: read `references/operations-and-observability-best-practices.md`. - Common failures: read `references/troubleshooting.md`. 5. Discover models before choosing one. - Use `GET /api/v1/models` for the full catalog. - Use its filters, pagination, and server-side sorting for large or cost-sensitive catalogs; use `GET /api/v1/model/:author/:slug` for one alias-aware lookup. - Use `GET /api/v1/models/user` when user or provider preferences matter. - Use `GET /api/v1/providers` when provider routing, privacy, or availability matter in the UI. - Use `GET /api/v1/models/:author/:slug/endpoints` when you need endpoint-level provider data, including promotional `pricing.discount`. - Derive free-model lists by filtering zero-priced entries from the model catalog. - Treat catalog and endpoint prices as already discounted. Never subtract the advertised percentage a second time. - Treat promotions as temporary endpoint properties, not as a permanent model-quality or routing policy. - Store model `id`, not model `name`. - Filter by `architecture.input_modalities` and `architecture.output_modalities` first; use name heuristics only as fallback. 6. Build requests in OpenAI-compatible format. - Send text-only prompts as normal chat `messages`. - Send images with `content` arrays containing a `text` part and one or more `image_url` parts. - Generate images by sending normal chat `messages` plus `modalities` that include `image`; pass `image_config` when output settings matter. - Discover generation models and endpoint-specific controls through `GET /api/v1/images/models` and its per-model endpoint route. - Use `POST /api/v1/images` for new image integrations. Keep chat-completions image output only for legacy compatibility. - Send PDFs with a `file` content part and, when needed, the `file-parser` plugin. - Default to `data:` URLs for private uploads and for any untrusted remote asset. Use remote `http(s)` URLs only from explicit allowlisted hosts that you control or trust. - Keep `tools` in every tool-calling request, including follow-up calls that only send tool results. - Preserve `reasoning_details` unchanged across tool turns when a reasoning model returns it. - Use `service_tier: "flex"` only when lower price is worth higher latency and lower availability; record the served tier. - Use the Batch API for non-interactive work that can finish within 24 hours. Do not assume a synchronous `:batch` model id is a drop-in replacement. 7. Choose response handling deliberately. - For plain prose, read `choices[0].message.content`. - For the Image API, read base64 assets from `data[*].b64_json` and preserve `media_type`; for legacy chat image output, read `choices[0].message.images`. - For structured data, prefer `response_format: { type: "json_schema", ... }` when the model supports `structured_outputs`. - Fall back to `response_format: { type: "json_object" }` when you need JSON but not full schema enforcement. - Use `assets/shared/parse-openrouter-response.ts` for robust text, generated-image, and tool-call extraction. - Use `assets/shared/stream-openrouter-sse.ts` for streaming. - Use `assets/shared/validate-structured-output.ts` with `zod` for type-safe parsing. - Use `assets/nextjs-template/components/openrouter-streaming-chat.tsx` as the end-to-end streaming UI example. 8. Reuse parsed PDFs when iterating. - If a PDF request returns assistant `annotations`, pass them back on follow-up requests to avoid reparsing cost and latency. - Preserve the original file message and append the annotated assistant message before the next user turn. 9. Verify the integration. - Run `assets/tests/smoke-curl.sh` for text, structured JSON, tools, image analysis, image generation, and PDF cases. - Run `assets/tests/smoke-catalogs.sh` for catalogs, endpoint discounts, key/credit diagnostics, and generation cost lookup. - Check both successful responses and non-2xx OpenRouter errors. - Log returned `usage`, `cost`, finish reason, resolved model id, and generation id for debugging. - Fetch `GET /api/v1/generation?id=...` when exact post-hoc cost or token accounting matters. - Compare candidate models on representative production inputs before switching for a temporary discount. - For billing incidents, inspect both `/api/v1/key` and `/api/v1/credits`; they report different scopes. ## Resources - Docs-check script: `scripts/check_openrouter_docs.py` - Installer script: `scripts/install_template.sh` - Next.js starter: `assets/nextjs-template/` - Express starter: `assets/express-template/` - Shared TypeScript helpers: `assets/shared/` - Smoke tests and fixtures: `assets/tests/` - Catalog and cost helper: `assets/shared/openrouter-catalog-and-cost.ts` - Image asset helper: `assets/shared/openrouter-generated-image-assets.ts` - Node image persistence helper: `assets/shared/openrouter-generated-image-assets-node.ts` - Catalogs, providers, free-model filters, and generation cost lookup: `references/catalogs-and-costs.md` - Discounts, workload comparisons, batch, service tiers, and credit guardrails: `references/discounts-and-cost-controls.md` - Catalog and routing production rules: `references/catalog-routing-best-practices.md` - Image generation usage, preview, storage, icons, and OG workflows: `references/image-generation-best-practices.md` - Tool calling and structured-output production rules: `references/tool-calling-and-structured-output-best-practices.md` - Operations, logging, and generation audit rules: `references/operations-and-observability-best-practices.md` ## Quality Rules - Prefer a server proxy with caching for model lists. - Keep model picker UIs searchable; plain `