Skip to main content
Version: main

openrouter

Generate images and extract colours using OpenRouter's multi-model API.

Description​

The openrouter plugin accesses various image generation models through OpenRouter, providing:

  • Access to multiple AI image generation models through a single API
  • Automatic model selection (cheapest or free model with image output support)
  • Image generation with colour extraction

Requirements​

Usage​

export OPENROUTER_API_KEY="your-api-key"
tinct generate -i openrouter --ai.prompt "<description>" [flags]

Storing your API key​

Rather than pasting your key into every shell session, retrieve it from a secret manager:

# GNOME Keyring / libsecret
export OPENROUTER_API_KEY=$(secret-tool lookup service openrouter)

# Bitwarden CLI
export OPENROUTER_API_KEY=$(bw get password openrouter)

# pass (password-store)
export OPENROUTER_API_KEY=$(pass show openrouter)

Flags​

AI flags (shared with google-genai)​

FlagDefaultDescription
--ai.promptImage description prompt (required)
--ai.modelautoAI model to use (auto-selects cheapest image-capable model)
--ai.list-modelsfalseList available models with live pricing and exit
--ai.no-extended-promptfalseDisable automatic wallpaper prompt enhancement
--ai.no-negative-promptfalseDisable default negative prompt
--ai.negative-promptCustom negative prompt to discourage certain elements

Plugin-specific flags​

FlagDefaultDescription
--openrouter.prefer-freetruePrefer free models when using auto selection

Common flags​

FlagDefaultDescription
--aspect-ratio16:9Image aspect ratio (1:1, 3:4, 4:3, 9:16, 16:9, 21:9)
--count32Number of colours to extract
--seed-modecontentSeed mode: content, manual, random

Examples​

Basic generation​

export OPENROUTER_API_KEY="your-api-key"

# Auto-selects cheapest image-capable model
tinct generate -i openrouter \
  --ai.prompt "cyberpunk city at night with neon lights" \
  -o all

With specific model​

tinct generate -i openrouter \
  --ai.prompt "watercolor painting of a mountain lake" \
  --ai.model "google/gemini-2.5-flash-image-preview" \
  --aspect-ratio "16:9" \
  -o all

With negative prompt​

tinct generate -i openrouter \
  --ai.prompt "serene japanese garden" \
  --ai.negative-prompt "people, text, watermark" \
  -o all

List available models​

tinct generate -i openrouter --ai.list-models

Dry run​

tinct generate -i openrouter \
  --ai.prompt "autumn forest" \
  --dry-run -o kitty

Model selection​

When --ai.model is auto (the default), tinct:

  1. Fetches the full model list from the OpenRouter API
  2. Filters to models with image output capability
  3. Sorts by cost (cheapest first)
  4. If --openrouter.prefer-free is true (default), selects a free model if available

To see what models are available with current pricing, use --ai.list-models.

How it works​

  1. Request: Send prompt to OpenRouter API
  2. Model routing: OpenRouter routes to selected model
  3. Generation: Image generated by chosen model
  4. Response: Base64 image returned
  5. Caching: Image cached locally
  6. Extraction: K-means colour extraction
  7. Wallpaper: Image provided to output plugins

Generated image location​

Images are cached in:

~/.cache/tinct/generated/openrouter/

Negative prompts​

Use negative prompts to exclude unwanted elements:

# Avoid certain styles
--ai.negative-prompt "cartoon, anime, illustration"

# Avoid artifacts
--ai.negative-prompt "blurry, low quality, distorted"

# Avoid elements
--ai.negative-prompt "text, watermark, people"

API credits​

OpenRouter uses a credit system. Different models have different costs. Monitor usage at OpenRouter dashboard.

Troubleshooting​

API key issues​

  • Verify key at openrouter.ai
  • Check OPENROUTER_API_KEY is exported
  • Ensure sufficient credits

Model not available​

  • Use --ai.list-models to see currently available models
  • Check model name spelling (use full model ID, e.g. google/gemini-2.5-flash-image-preview)
  • Try a different model or use auto

Poor results​

  • Adjust prompt for the model
  • Try different model
  • Use negative prompts

See also​