Skip to main content

OpenRouter best practices

Last updated 2 min read

OpenRouter model IDs are routing aliases in `provider/model` form, not provider-native names. Coolhand records the alias you sent, so a change to the upstream provider behind that alias is invisible in your logs. Pin the alias you intend to compare over time before relying on its cost trend.

Model IDs use provider/model routing format

OpenRouter model identifiers are routing aliases, not provider-native names:

anthropic/claude-3-5-sonnet
openai/gpt-4o
google/gemini-2.5-pro-preview
meta-llama/llama-3.1-70b-instruct

The Model field in Coolhand shows the OpenRouter ID. When using openrouter/auto or similar auto-routing aliases, the logged model reflects the alias, not the model actually selected.

Fallback routing can silently change the model

OpenRouter automatically falls back to another provider when one is rate-limited or unavailable. If you see unexpected model IDs in logs, fallback routing is the likely cause. OpenRouter does not guarantee the model you specified was the one used.

Structured outputs

OpenRouter defines its own unified response_format that it enforces independently — it is not a simple passthrough. Supported types are json_object and json_schema. OpenRouter validates the request against its own schema and returns an error if the target model doesn't support the requested format. A Response Healing plugin is also available, which attempts to repair malformed JSON before returning it to the caller.

Docs: https://openrouter.ai/docs/guides/features/structured-outputs

Caching

Coolhand captures Cached Input Tokens when the target provider reports a cache hit. Cache Creation Tokens are never surfaced for OpenRouter logs — even when routing to a provider (like Anthropic) that reports cache creation separately.

Cache TTL and invalidation depend entirely on the target provider. OpenRouter does not expose cache lifecycle details.

Batch processing

OpenRouter has no native batch API. If you need batch processing for a specific provider, call that provider directly:

Latency

Coolhand inherits OpenAI's latency logic for OpenRouter: it checks for an openai-processing-ms response header first, then falls back to the collector-provided duration_ms. Whether OpenRouter forwards that header is not documented — in practice, the fallback duration_ms (wall-clock including routing overhead) is the value most often captured. Not directly comparable to direct-provider latency figures.

Related articles

  • Azure OpenAI best practices

    Azure logs record your deployment name, not the underlying model version, so `my-gpt4o-prod` appears where you might ...

  • AWS Bedrock best practices

    AWS Bedrock exposes two API surfaces and Coolhand records them as separate sources: `bedrock` for the OpenAI-compatib...

  • Ollama best practices

    Ollama identifies models as `name:tag`, and Coolhand treats each tag as a distinct model, so `llama3.1:8b` and `llama...

  • Google Gemini best practices

    The Gemini API carries system instructions in a top-level `system_instruction` field rather than a system-role messag...