OpenRouter Model Fallback and Provider Ordering

Use OpenRouter's request-level models array and provider preferences for automatic failover.

OpenRouter accepts a models array: if the first model errors (rate limit, downtime, moderation), it tries the next. provider preferences control which upstream hosts serve a model.

Steps

1. Create an OpenRouter API key and export it as OPENROUTER_API_KEY.
2. List your models in priority order in the models array (check slugs at openrouter.ai/models).
3. Set provider preferences (order, fallbacks, data collection) to control which hosts serve each model.
4. Send the request and log the response's model field.

Request

{
  "models": ["anthropic/claude-sonnet-5.5", "openai/gpt-6-sol", "meta-llama/llama-3.1-70b-instruct"],
  "messages": [{"role": "user", "content": "Summarize this changelog..."}],
  "provider": {
    "order": ["Anthropic", "OpenAI"],
    "allow_fallbacks": true,
    "data_collection": "deny"
  }
}

curl https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H 'Content-Type: application/json' -d @request.json

The response's model field tells you which model actually answered; log it. Verify current slugs at openrouter.ai/models.

Failure modes

• Model slugs get retired; check openrouter.ai/models.
• Fallback model differs in behavior and price; log the answering model.
• Provider restrictions that are too strict leave no available route.

Markdown version: /blueprints/openrouter-fallback-models.md

Related blueprints