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 checking architecture.output_modalities for image.
- 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.
Choose response handling deliberately.
- For plain prose, read choices[0].message.content.
- For image generation, 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.
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.
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 models, user models, providers, free-model filtering, image-output model discovery, 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.

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
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 <select> breaks down on large catalogs.
Use architecture.input_modalities and architecture.output_modalities as the primary capability signals.
Treat pricing fields as strings from the API; convert explicitly if you need numeric math.
Persist generation ids anywhere later cost inspection matters.
Prefer exact generation lookup over estimated UI-only price math when a completed request id exists.
Include the organization prefix in model ids such as openai/gpt-4o-mini.
Expect choices to always be an array.
For streaming, expect SSE comment lines and ignore them.
For PDFs, choose pdf-text for clean text PDFs, mistral-ocr for scanned or image-heavy PDFs, and native only when the selected model supports file input natively.
Do not assume every model supports response_format, structured_outputs, tools, or every OpenAI parameter; check supported_parameters first.
When a request depends on specific parameters such as tools or response_format, prefer provider.require_parameters: true.

References

Model discovery, caching, and picker UX: references/models-and-ui.md
Catalogs, providers, free-model filters, and generation cost lookup: references/catalogs-and-costs.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
Text, image analysis, image generation, and PDF request patterns plus response handling: references/requests-and-responses.md
Tool calling and agentic loops: references/tools-and-function-calling.md
Tool calling and structured-output production rules: references/tool-calling-and-structured-output-best-practices.md
Model routing, provider routing, and fallbacks: references/routing-and-fallbacks.md
Operations, logging, and generation audit rules: references/operations-and-observability-best-practices.md
Troubleshooting and failure diagnosis: references/troubleshooting.md
Docs-check workflow: references/docs-check-workflow.md

openrouter-integration

Safety Notice

Copy this and send it to your AI assistant to learn