How to Use the OpenRouter API to Access GPT, Claude, Gemini & More: 2026 Complete Guide

OpenRouter is a unified LLM gateway: you create one account, one API key, and call a single OpenAI-compatible endpoint — https://openrouter.ai/api/v1/chat/completions — to reach models from 70+ providers and 400+ model IDs. Swap models by changing the model string; no new SDK, no new billing portal, no new auth header scheme.

Model names follow a vendor/model slug convention. Examples that work today on OpenRouter:

• openai/gpt-5.6-sol — OpenAI flagship reasoning
• anthropic/claude-sonnet-4 — Anthropic balanced tier
• google/gemini-2.5-pro — Google multimodal flagship
• deepseek/deepseek-v4 — DeepSeek MoE at aggressive list pricing

Because the API shape matches OpenAI Chat Completions, existing clients — LangChain, LiteLLM, the official OpenAI SDK, Cursor, Hermes Agent — often need only a base_url change. OpenRouter also exposes /models, /generation, and provider metadata so you can build routing logic without hard-coding vendor endpoints. Real-world throughput on the platform exceeds 100 trillion tokens per month as of mid-2026; our June rankings breakdown shows how that traffic splits across models and geographies.

• Key sprawl: Every vendor ships its own dashboard, rate limits, and invoice format. OpenRouter consolidates billing and observability into one ledger — critical when agents fire thousands of calls per hour across model tiers.
• Model churn: Flagship IDs change monthly. A gateway with a live /models catalog and automatic provider failover beats hard-coded URLs that break on deprecation day — see our weekly billing truth article for how fast share shifts.
• Failover gaps: Direct Anthropic or OpenAI outages stall entire products. OpenRouter's fallback JSON lets you specify an ordered model list; the gateway tries the next slug when a provider returns 429 or 5xx.
• Experiment friction: Comparing GPT vs Claude vs Gemini on the same prompt historically meant three SDKs and three secrets. OpenRouter makes A/B routing a one-line config change in agent env files.
• Ops blind spots: Without centralized routing, teams discover cost overruns in three separate vendor emails. OpenRouter's dashboard attributes spend by model and application ID — pair with app rankings in our CLI tools guide.

OpenRouter is not magic. It adds a routing hop — typically 10–80 ms of extra latency depending on region — and it cannot replicate vendor-exclusive surfaces (OpenAI Assistants threads, Claude Projects, Gemini Live API) through a generic chat endpoint. Know those boundaries before you migrate production traffic.

OpenRouter supports two routing philosophies. Most teams start with Model Routing (pick a model slug; OpenRouter picks the best available provider). Advanced teams use Provider Routing (pin or block specific backends for compliance or latency).

Fallback chains combine both: pass an array of model slugs in the request body or use the models parameter so OpenRouter tries anthropic/claude-sonnet-4, then openai/gpt-5.6-sol, then deepseek/deepseek-v4 until one succeeds. This is the production pattern for agent loops that cannot afford a hard stop on a single vendor outage.

Advantage 1 — One integration surface: Ship once against OpenAI-compatible JSON; route to any vendor. Agent frameworks (Hermes, LangGraph, CrewAI) inherit multi-model support without plugin rewrites.

Advantage 2 — Transparent list pricing: OpenRouter passes through provider token rates with no markup on tokens. You pay a 5.5% fee only when purchasing platform credits, not per token at list price. BYOK users bring vendor keys and get 1 million requests per month free on the OpenRouter routing layer.

Advantage 3 — Free tier for experiments: OpenRouter hosts 25+ free models. New accounts receive 50 free requests per day on those models without buying credits. After a $10 credit top-up, the daily free-model allowance rises to 1,000 requests per day — enough for CI smoke tests and hobby agents.

Advantage 4 — Live model catalog: The GET /api/v1/models endpoint returns pricing, context length, and modality flags. Automated routers can promote or demote models weekly based on leaderboard data instead of manual env edits.

Advantage 5 — Observability: Generation IDs, per-request cost estimates, and app-level attribution (when clients identify themselves) make FinOps for LLM spend tractable for the first time at small-team scale.

• Data point 1: 70+ providers, 400+ models, one endpoint.
• Data point 2: 5.5% credit purchase fee, zero token markup at list rates.
• Data point 3: Free tier: 50/day → 1,000/day after $10 top-up on 25+ free models.
• Data point 4: BYOK: 1M requests/month free on the routing layer.

Every request requires an Authorization: Bearer sk-or-v1-... header. Optional but recommended headers:

• HTTP-Referer — your site URL; used for OpenRouter rankings attribution
• X-Title — your app name; appears on public app leaderboards if tracking is enabled

The request body mirrors OpenAI Chat Completions: model, messages, optional stream, temperature, max_tokens, and OpenRouter extensions such as models (fallback array) and provider (routing preferences). Responses include choices, usage, and an OpenRouter-specific id you can trace in the dashboard.

Replace sk-or-v1-xxxxxxxx with your key from the runbook below. All examples target the same model slug so you can diff outputs across languages.

curl https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer sk-or-v1-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "HTTP-Referer: https://nukcloud.com" \
  -H "X-Title: NUKCLOUD Agent Demo" \
  -d '{
    "model": "anthropic/claude-sonnet-4",
    "messages": [{"role": "user", "content": "Summarize OpenRouter in 40 words."}]
  }'

import os
import requests

resp = requests.post(
    "https://openrouter.ai/api/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {os.environ['OPENROUTER_API_KEY']}",
        "HTTP-Referer": "https://nukcloud.com",
        "X-Title": "NUKCLOUD Agent Demo",
    },
    json={
        "model": "openai/gpt-5.6-sol",
        "messages": [{"role": "user", "content": "Write a Python hello world."}],
    },
    timeout=120,
)
resp.raise_for_status()
print(resp.json()["choices"][0]["message"]["content"])

from openai import OpenAI

client = OpenAI(
    base_url="https://openrouter.ai/api/v1",
    api_key=os.environ["OPENROUTER_API_KEY"],
)

completion = client.chat.completions.create(
    model="google/gemini-2.5-pro",
    messages=[{"role": "user", "content": "Explain model routing vs provider routing."}],
)
print(completion.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://openrouter.ai/api/v1",
  apiKey: process.env.OPENROUTER_API_KEY,
  defaultHeaders: {
    "HTTP-Referer": "https://nukcloud.com",
    "X-Title": "NUKCLOUD Agent Demo",
  },
});

const completion = await client.chat.completions.create({
  model: "deepseek/deepseek-v4",
  messages: [{ role: "user", content: "Refactor this function to async/await." }],
});
console.log(completion.choices[0].message.content);

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",
  },
  body: JSON.stringify({
    model: "anthropic/claude-sonnet-4",
    stream: true,
    messages: [{ role: "user", content: "Stream a short poem about APIs." }],
  }),
});

const reader = res.body.getReader();
const decoder = new TextDecoder();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  const chunk = decoder.decode(value);
  for (const line of chunk.split("\n")) {
    if (line.startsWith("data: ") && line !== "data: [DONE]") {
      const json = JSON.parse(line.slice(6));
      process.stdout.write(json.choices?.[0]?.delta?.content ?? "");
    }
  }
}

{
  "models": [
    "anthropic/claude-sonnet-4",
    "openai/gpt-5.6-sol",
    "deepseek/deepseek-v4"
  ],
  "messages": [
    {"role": "user", "content": "If the primary model is down, this still returns."}
  ]
}

curl https://openrouter.ai/api/v1/models \
  -H "Authorization: Bearer sk-or-v1-xxxxxxxx" | jq '.data[] | {id, pricing}'

Store keys in mode-600 env files on your agent host — not in git. On a dedicated cloud Mac, place secrets under ~/.hermes/secrets/ or a tenant-scoped vault and load them from launchd or systemd units as described in our Hermes install articles.

BYOK (Bring Your Own Key): Attach your existing OpenAI, Anthropic, or other vendor keys in the OpenRouter dashboard. Routing still flows through OpenRouter's observability layer, but billing hits your vendor account. The platform includes 1 million BYOK requests per month free; beyond that, a small per-request platform fee applies — still often cheaper than maintaining custom proxy code.

Free models: More than 25 models carry a $0 list price on OpenRouter. New accounts get 50 requests per day on those models without purchasing credits. After you add $10 in platform credits, the daily cap on free models increases to 1,000 requests per day — suitable for staging agents and automated regression prompts.

Credit economics: When you buy OpenRouter credits, a 5.5% processing fee applies to the purchase amount — not an invisible per-token surcharge. Token charges match provider list rates displayed on the model page. For high-volume teams, compare total cost (credits + hop latency) against direct enterprise agreements quarterly.

1. 01
   Create an OpenRouter account: Sign up at openrouter.ai with a team email you control for billing alerts. Enable two-factor authentication before attaching payment methods.
2. 02
   Generate an API key: Open Settings → Keys → Create Key. Label it by environment (prod-agent, staging-ci). Copy once; OpenRouter will not show the full secret again.
3. 03
   Set spending limits: Configure a monthly credit cap and email notifications at 50% and 90% thresholds. Agent loops can burn budgets overnight without caps — set limits before the first daemon starts.
4. 04
   Store the key securely on your host: Write export OPENROUTER_API_KEY="sk-or-v1-..." to a mode-600 file such as ~/.secrets/openrouter.env. Never commit keys to git or paste them into Slack. On NUKCLOUD nodes, keep secrets on the dedicated tenant volume.
5. 05
   Smoke-test with curl: Run the minimal curl example from the code section against a cheap or free model slug. Confirm HTTP 200, parse usage tokens, and verify the charge appears in the dashboard within one minute.
6. 06
   Wire your agent or SDK: Point OpenAI SDK clients at https://openrouter.ai/api/v1, set HTTP-Referer and X-Title for attribution, and configure a fallback models array before promoting to production. Review specs on the pricing page if you need a dedicated cloud Mac host for 24/7 agents, then provision via the order flow.

Bilingual sites often see strong Chinese impressions and weak English clicks. Before blaming content quality, run this checklist — many EN gaps are technical, not editorial.

• Google Search Console segmentation: Filter performance by page path /en/ vs /zh/. If EN pages are indexed but CTR is near zero, titles and meta descriptions are misaligned with English query intent — not a ranking penalty.
• CDN / WAF geo rules: Confirm US and EU PoPs serve /en/blog/ with HTTP 200 and full HTML — not a challenge page, soft 404, or redirect loop to default locale.
• hreflang integrity: List pages should declare reciprocal hreflang pairs for all eight locales. Detail pages use canonical URLs only (per NUKCLOUD convention). Broken reciprocity causes Google to ignore language signals.
• Machine-translation fingerprints: EN pages that mirror zh sentence structure trigger quality demotion. English articles must be independently authored with native keyword placement — this post is an example of localization, not translation.
• Backlink locale mismatch: If 90% of inbound links point to /zh/, English URLs inherit weak authority. Pursue EN-language citations: GitHub READMEs, Dev.to, Hacker News, and English developer newsletters.

English keyword matrix (priority tiers):

Title signals: Lead with the user task ("How to Use the OpenRouter API") plus model names (GPT, Claude, Gemini) and the year. H1 uses blog-hero-title-accent for the guide qualifier; keep one H1 per page.

Meta template: [Primary keyword]: [secondary models/features]. [Proof element — routing/pricing/code]. [Outcome — setup runbook / agent deployment]. Stay under 160 characters; match the snippet to the first sentence of .blog-lead.

Localization, not translation: English posts should cite Western developer contexts (OpenAI SDK, GitHub Actions, GSC) while zh posts cite Baidu, WeChat ecosystem, and domestic model names. Shared facts (pricing numbers, endpoint URLs) stay identical; prose and examples diverge.

Chinese SEO summary for bilingual owners: zh content should target 长尾词 like "OpenRouter API 教程" and "多模型统一接口" on Baidu and WeChat search; prioritize 知乎 and 掘金 republishing with canonical pointing to nukcloud.com/zh/blog/. Keep slug and id aligned across locales for hreflang on index pages. Invest in中文 backlinks from AI developer communities; English authority does not automatically transfer.

• URL structure: https://nukcloud.com/{lang}/blog/{slug}.html — language prefix, shared slug across all eight locales, date suffix in filename for freshness signals.
• Canonical: Each detail page declares one self-referencing canonical (this page: https://nukcloud.com/en/blog/2026-openrouter-api-guide-gpt-claude-gemini-20260724.html). No hreflang on detail pages per NUKCLOUD convention; hreflang lives on blog/index.html.
• Sitemap: Regenerate via node .cursor/scripts/generate-sitemap.js after publishing; validate with validate-sitemap.js. Submit updated sitemap in GSC for both nukcloud.com property and the /en/ URL prefix if segmented.
• Schema: BlogPosting JSON-LD with datePublished, dateModified, and nested FAQPage in mainEntity — implemented in this page's head block. FAQ content must match visible .faq-row answers.

P0 launch checklist: (1) HTML validates, canonical correct; (2) blog-data.js entry live in all locales; (3) sitemap regenerated; (4) IndexNow ping; (5) GSC URL inspection submitted for EN URL.

P1 week-one: Internal links from three existing OpenRouter posts; share on one English developer forum; verify Matomo events on blog pageviews.

P2 month-one: Track EN organic impressions vs zh in GSC; measure avg position for "OpenRouter API"; revisit title if CTR < 2% with position < 15.

Metrics to watch: GSC impressions/clicks by locale, average position for P0 keywords, OpenRouter referral traffic (if you set HTTP-Referer), time-on-page from Matomo, and inbound links to /en/blog/ from ahrefs or GSC links report.

OpenRouter solves model access; it does not solve host stability. Persistent agents — Hermes gateways, Kilo Code daemons, custom LangGraph workers — need macOS or Linux hosts that keep long HTTP/2 streams and SSH sessions alive without eviction. Shared minute-pool macOS rentals often suffer bandwidth jitter, neighbor CPU contention, and connection resets that look like "model hallucinations" when the client actually dropped mid-stream.

For production agent workloads, NUKCLOUD multi-region bare-metal Mac and cloud Mac nodes provide dedicated Apple Silicon with auditable tenant boundaries: pin OpenRouter env files on a tenant-scoped volume, run gateways under launchd with KeepAlive, and colocate Git remotes beside the node to cut clone latency. When monthly OpenRouter spend exceeds high-memory Mac rental and your codebase touches iOS or macOS targets, the combined stack — gateway routing plus dedicated host — typically beats laptop-plus-VPN or oversubscribed pools on both uptime and FinOps clarity.

Review hardware tiers on the pricing page, provision through the order flow, and follow our CLI ranking runbook to pick a client before you point production keys at a new default model.