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

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

1. Check the docs before making non-trivial changes.
2. Run scripts/check_openrouter_docs.py --quick when accuracy matters or the integration seems stale.
3. If the script flags warnings, read references/docs-check-workflow.md and browse only the flagged official pages.
4. Reconcile templates, headers, and parameter usage with the current docs before coding.

1. Keep secrets server-side.
2. Do not expose OPENROUTER_API_KEY in browser code.
3. Put a server route in front of OpenRouter for model discovery and chat calls.
4. Set HTTP-Referer and X-OpenRouter-Title headers when the app has a stable URL and title.
5. 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.

1. Install a starter instead of retyping boilerplate.
2. Use scripts/install_template.sh with --template nextjs or --template express.
3. Override base path and env var names at install time when the target project already has conventions.
4. Copy shared helpers, streaming UI example, and test fixtures with the template.

1. Decide what you are integrating.
2. Catalog, providers, free-model filters, or generation cost lookup: read references/catalogs-and-costs.md.
3. Model catalog or picker: read references/models-and-ui.md.
4. Model selection, provider filters, or fallback policy that should be production-friendly: read references/catalog-routing-best-practices.md.
5. Text, image analysis, image generation, or PDF inference: read references/requests-and-responses.md.
6. End-to-end image asset workflows such as icons, OG images, preview, and storage: read references/image-generation-best-practices.md.
7. Tool calling or an agentic loop: read references/tools-and-function-calling.md.
8. Tool reliability or structured-output extraction that should survive production use: read references/tool-calling-and-structured-output-best-practices.md.
9. Routing and failover policy: read references/routing-and-fallbacks.md.
10. Logging, generation audit, and cost observability: read references/operations-and-observability-best-practices.md.
11. Common failures: read references/troubleshooting.md.

1. Discover models before choosing one.
2. Use GET /api/v1/models for the full catalog.
3. Use GET /api/v1/models/user when user or provider preferences matter.
4. Use GET /api/v1/providers when provider routing, privacy, or availability matter in the UI.
5. Use GET /api/v1/models/:author/:slug/endpoints when you need endpoint-level provider data.
6. Derive free-model lists by filtering zero-priced entries from the model catalog.
7. Store model id, not model name.
8. Filter by architecture.input_modalities and architecture.output_modalities first; use name heuristics only as fallback.

1. Build requests in OpenAI-compatible format.
2. Send text-only prompts as normal chat messages.
3. Send images with content arrays containing a text part and one or more image_url parts.
4. Generate images by sending normal chat messages plus modalities that include image; pass image_config when output settings matter.
5. Choose image-output models from the live catalog by checki