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

curl -s https://openrouter.ai/api/v1/models \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Accept: application/json"

Curl: list providers

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

curl -s "https://openrouter.ai/api/v1/generation?id=$GENERATION_ID" \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Accept: application/json"

Fetch: free models from the catalog

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

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

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

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-3.1-flash-image-preview",
    messages: [
      {
        role: "user",
        content: "Generate a clean product-style illustration of a glass teacup on a plain background.",
      },
    ],
    modalities: ["image", "text"],
    image_config: { size: "1024x1024" },
  }),
});

const json = await res.json();
const imageUrl = json?.choices?.[0]?.message?.images?.[0]?.image_url?.url;

Fetch: PDF input with file-parser

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: "pdf-text" },
      },
    ],
    response_format: { type: "json_object" },
    temperature: 0,
  }),
});

Workflow

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.
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.
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.
Decide what you are integrating.
- Catalog, providers, free-model filters, or generation cost lookup: read references/catalogs-and-costs.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, 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.
Discover models before choosing one.
- Use GET /api/v1/models for the full catalog.
- 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.
- Derive free-model lists by filtering zero-priced entries from the model catalog.
- Store model id, not model name.
- Filter by architecture.input_modalities and architecture.output_modalities first; use name heuristics only as fallback.
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.
- Choose image-output models from the live catalog by checki

openrouter-integration