Skip to main content
You do not have to tell the gateway which provider to use. For most models, it figures it out. When it can’t, you add one header.

How detection works

The gateway resolves the provider in this order:
1

X-Toolken-Provider header (if present)

If you set X-Toolken-Provider, that value wins immediately. An unknown value returns a 400 invalid_provider error.
2

Request path

A request to /v1/messages always goes to Anthropic, regardless of the model name.
3

Model name

The gateway matches the model name against a prefix map and an exact-match catalog. claude-3-5-sonnet-20241022 routes to Anthropic; gpt-4o routes to OpenAI; gemini-2.5-flash routes to Gemini.
4

Error

If none of the above resolves to a provider, the gateway returns 400 invalid_provider and tells you to set X-Toolken-Provider.

When to use X-Toolken-Provider

Auto-detection covers most cases. Set X-Toolken-Provider when:
  • You are routing through OpenRouter (model names like meta-llama/llama-3.3-70b-instruct overlap with real provider prefixes, so auto-detection is disabled for OpenRouter).
  • You are using a provider-hosted open-source model whose name does not carry a provider prefix (e.g. llama-3.3-70b on Together AI or Cerebras).
  • You want to be explicit in production code so a model rename never silently changes the provider.

Sending X-Toolken-Provider

Add the header alongside your existing headers. The value is the lowercase provider name.

Provider and path must be compatible

The gateway validates that the provider supports the path you are calling. Anthropic handles /v1/messages and /v1/models; every other provider handles the OpenAI-compatible paths (/v1/chat/completions, /v1/embeddings, etc.). Sending a claude- model to /v1/chat/completions without X-Toolken-Provider is fine: the gateway detects Anthropic and returns 400 incompatible_path because Anthropic requires /v1/messages. The error message tells you exactly what to fix.
If you get incompatible_path, check that your base URL and model match. Anthropic SDK users: set base_url to https://gateway.toolken.ai (without /v1) and the SDK appends /v1/messages automatically.

X-Toolken-Provider reference

Next

Providers Overview

The full provider list and how BYOK works.

Anthropic & Gemini

Special surfaces for Anthropic and Gemini.