OpenRouter Provider

OpenRouter Provider

OpenRouter lets you use any of 100+ models through a single API. This is useful when you want to use Claude, GPT-4, Llama, or other models instead of (or alongside) Google Gemini.

Why OpenRouter?

• Model variety: Access Claude, GPT-4, Llama, Mistral, and many other models
• Single API key: One key works for all models
• Pay-per-use: No subscriptions, just pay for what you use
• Fallback options: If one model is down, switch to another

Setup

1. Get an API Key

Sign up at openrouter.ai and create an API key at openrouter.ai/keys.

2. Set the Environment Variable

Add to your .env file:

OPENROUTER_API_KEY=sk-or-v1-your-key-here

Or export directly:

export OPENROUTER_API_KEY=sk-or-v1-your-key-here

3. Use via CLI

VLM (planning, styling, critique):

paperbanana generate \
  --input method.txt \
  --caption "Overview of our framework" \
  --vlm-provider openrouter \
  --vlm-model google/gemini-3-flash-preview

Image generation:

paperbanana generate \
  --input method.txt \
  --caption "Overview of our framework" \
  --vlm-provider openrouter \
  --vlm-model anthropic/claude-3.5-sonnet \
  --image-provider openrouter_imagen \
  --image-model google/gemini-3-pro-image-preview

4. Use via Config

Create a config file (configs/openrouter.yaml):

vlm:
  provider: openrouter
  model: anthropic/claude-3.5-sonnet

image:
  provider: openrouter_imagen
  model: google/gemini-3-pro-image-preview

pipeline:
  refinement_iterations: 3

Then:

paperbanana generate \
  --input method.txt \
  --caption "Overview" \
  --config configs/openrouter.yaml

5. Use via Python API

from paperbanana import PaperBananaPipeline, GenerationInput, DiagramType
from paperbanana.core.config import Settings

settings = Settings(
    vlm_provider="openrouter",
    vlm_model="anthropic/claude-3.5-sonnet",
    image_provider="openrouter_imagen",
    image_model="google/gemini-3-pro-image-preview",
)

pipeline = PaperBananaPipeline(settings=settings)
result = await pipeline.generate(
    GenerationInput(
        source_context="Our framework consists of...",
        communicative_intent="Overview of the proposed method.",
        diagram_type=DiagramType.METHODOLOGY,
    )
)

Available Models

VLM Models (for planning, styling, critique)

Model	ID	Notes
Claude 3.5 Sonnet	anthropic/claude-3.5-sonnet	Excellent for planning and critique
Claude 3 Opus	anthropic/claude-3-opus	Most capable, higher cost
GPT-4o	openai/gpt-4o	Strong all-around
GPT-4 Turbo	openai/gpt-4-turbo	Fast, capable
Gemini 3 Flash	google/gemini-3-flash-preview	Fast and cheap
Llama 3.1 70B	meta-llama/llama-3.1-70b-instruct	Open-source, good value

Image Generation Models

Model	ID	Notes
Gemini 3 Pro Image	google/gemini-3-pro-image-preview	Best for diagrams

Note: Not all models support image generation. Currently, Gemini 3 Pro via OpenRouter is the recommended choice for image generation.

MCP Server Configuration

For Claude Code:

{
  "mcpServers": {
    "paperbanana": {
      "command": "uvx",
      "args": ["--from", "paperbanana[mcp]", "paperbanana-mcp"],
      "env": {
        "OPENROUTER_API_KEY": "sk-or-v1-your-key-here"
      }
    }
  }
}

Mixing Providers

You can use different providers for VLM and image generation:

# Claude for planning/critique, Gemini for image generation
paperbanana generate \
  --input method.txt \
  --caption "Overview" \
  --vlm-provider openrouter \
  --vlm-model anthropic/claude-3.5-sonnet \
  --image-provider google_imagen \
  --image-model gemini-3-pro-image-preview

This requires both OPENROUTER_API_KEY and GOOGLE_API_KEY to be set.

Cost Comparison

OpenRouter charges per token/request. Approximate costs for generating one diagram (3 iterations):

Setup	Approximate Cost
Gemini Flash (VLM) + Gemini Pro (Image)	~$0.02-0.05
Claude Sonnet (VLM) + Gemini Pro (Image)	~$0.10-0.20
GPT-4o (VLM) + Gemini Pro (Image)	~$0.15-0.30

Check openrouter.ai/models for current pricing.

Troubleshooting

"API key not valid": Verify your key at openrouter.ai/keys. Make sure you're using the full key including the sk-or-v1- prefix.

"Model not found": Check the exact model ID at openrouter.ai/models. Model IDs are case-sensitive.

"No image data in response": Not all models support image generation. Use google/gemini-3-pro-image-preview for the image provider.

Rate limits: OpenRouter has per-minute limits based on your account tier. Add delays between batch generations if needed.