OpenRouter Chat Completions API: Endpoint, Auth, Example

The OpenRouter chat completions endpoint is POST https://openrouter.ai/api/v1/chat/completions. You authenticate with the header Authorization: Bearer <OPENROUTER_API_KEY> and send a JSON body with a model and a messages array (OpenRouter API reference, 2026). Paste this into a terminal to test it:

curl https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "What is the capital of France?"}]
  }'

The reply is JSON. The answer text is in choices[0].message.content, and token counts are in usage. OpenAI-compatible SDKs take the base URL https://openrouter.ai/api/v1, without /chat/completions. Some apps ask for the full endpoint URL instead, so check what the field expects.

Key Takeaways

• Endpoint: POST https://openrouter.ai/api/v1/chat/completions. Auth: Authorization: Bearer <key>.
• Required body fields: messages. Set model to an ID such as openai/gpt-4o-mini.
• OpenAI SDKs work after you change two values: the base URL and the API key.
• Fallbacks use the models array. The route parameter is deprecated.
• OpenRouter passes through provider prices with no markup on inference. It charges a fee when you buy credits (OpenRouter FAQ, 2026).
• Common errors: 401 (bad key), 402 (no credits), 429 (rate limit), 502 (model down), 503 (no provider matches).

What is the OpenRouter chat completions endpoint?

The OpenRouter chat completions endpoint is one URL that sends your messages to a model from many providers and returns the reply in the OpenAI Chat Completions format. OpenRouter describes the schema as very similar to the OpenAI Chat API and normalizes it across models (OpenRouter API overview, 2026).

The request body accepts these common fields:

Field	What it does
messages	Required. The conversation, as a list of role and content objects.
model	The model ID, in the form provider/model-name.
models	A list of model IDs to try in order if the first one fails.
max_tokens, temperature, top_p	Standard sampling controls.
stream	Set to true to receive the reply in chunks. Default is false.
tools, tool_choice	Function calling, on models that support it.
provider	Your routing preferences when several providers serve one model.

The full parameter list is in the OpenRouter API reference. The models page lists every model ID with current prices.

How do you authenticate with the OpenRouter chat completions API?

You authenticate by sending your OpenRouter API key as a Bearer token in the Authorization header (OpenRouter authentication docs, 2026). Create the key on the OpenRouter keys page, give it a name, and optionally set a credit limit. Store it in an environment variable, not in your code.

Two optional headers help OpenRouter attribute your traffic: HTTP-Referer (your site URL) and X-OpenRouter-Title (your app name; X-Title is also accepted).

How do you call it from Python or JavaScript?

You call it from Python or JavaScript with the official OpenAI SDK by pointing base_url at https://openrouter.ai/api/v1 and using your OpenRouter key. No other code changes are needed.

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://openrouter.ai/api/v1",
    api_key=os.environ["OPENROUTER_API_KEY"],
)

response = client.chat.completions.create(
    model="openai/gpt-4o-mini",
    messages=[{"role": "user", "content": "Explain vector databases in one paragraph."}],
)
print(response.choices[0].message.content)

The openai npm package works the same way with baseURL. Any plain HTTP client works too, as the curl example above shows.

How does model routing work?

Model routing works through the model field. You name one model, and OpenRouter sends the request to a provider that serves it. Model IDs have the form provider/model-name, for example openai/gpt-4o-mini, anthropic/claude-sonnet-4.6 or google/gemini-2.5-pro. These IDs were present in the live model list on 30 October 2026 (OpenRouter models API, 2026). Model IDs change as new versions arrive, so copy an ID from the models page.

When several providers serve the same model, the provider object sets your preference, for example sorting by throughput or price. The options are in the provider routing guide.

How do model fallbacks work?

Model fallbacks work through the models array. OpenRouter tries the first model, and if it errors, it tries the next one (OpenRouter model fallbacks, 2026).

{
  "models": ["anthropic/claude-sonnet-4.6", "openai/gpt-4o-mini"],
  "messages": [{"role": "user", "content": "Hello"}]
}

Any error can trigger a fallback, including downtime, rate limits and moderation flags. If a :free model falls back to a paid model, you pay the paid price. The older route parameter is marked deprecated in the API reference, so use models instead. There is no lowest-cost route value in the current reference.

How much does the OpenRouter chat completions API cost?

You pay the underlying provider's per-token price, and OpenRouter adds no markup on inference. OpenRouter charges a fee when you buy credits (OpenRouter FAQ, 2026). Prices differ per model, so check the models page before you choose.

Models whose ID ends in :free cost nothing per token but have limits. With under 10 credits purchased, you get 20 requests per minute and 50 per day. With at least 10 credits purchased, the daily cap is 1,000 (OpenRouter limits docs, 2026).

What errors does the endpoint return?

The endpoint returns standard HTTP status codes, and the error body has a code and a message (OpenRouter errors docs, 2026).

Code	Meaning	What to do
400	Invalid or missing parameters	Check the JSON body.
401	Invalid credentials or disabled key	Create or re-enable the key.
402	Not enough credits	Add credits.
403	Blocked by permissions, a guardrail or moderation	Read the message for the cause.
408	Request timed out	Retry.
429	Rate limited	Wait, using the Retry-After header when present.
502	The chosen model is down or sent an invalid response	Retry or add a fallback model.
503	No provider meets your routing requirements	Loosen your provider settings.

Streaming requests can also fail after the first chunk. In that case the error arrives inside the stream as a chunk, so check each chunk for an error field.

How do you use the endpoint in a workflow with CodeWords?

CodeWords is a workflow automation platform that connects to 3,000+ integrations (CodeWords marketing claims, 2026). You describe the job, and Cody builds the workflow, connects your tools and keeps it running on a schedule or a trigger. The CodeWords docs include an openrouter_multi_model_chat template that sends requests to https://openrouter.ai/api/v1/chat/completions with your OPENROUTER_API_KEY (CodeWords docs, 2026). Browse the templates for starting points and the pricing page for plan details.

For related reading, see OpenRouter embeddings, what an API gateway is and LLM orchestration frameworks.

FAQs: OpenRouter Chat Completions

Is OpenRouter ai API free?

Creating a key is free, and models with IDs ending in :free have no per-token cost. Free models are capped at 20 requests per minute, and 50 requests per day if you have bought under 10 credits (OpenRouter limits docs, 2026). Paid models bill at the provider's price.

How much does OpenRouter API cost?

OpenRouter passes through the provider's per-token price with no markup on inference (OpenRouter FAQ, 2026). It charges a fee when you buy credits. Each model has its own price, shown on the OpenRouter models page, so the cost of one request depends on the model you pick and the number of input and output tokens it uses.

What does an OpenRouter do?

OpenRouter is one API that routes your request to models from many providers, such as OpenAI, Anthropic and Google (OpenRouter API overview, 2026). You use one key and one request format. It also handles fallbacks between models and providers, so a request can move to another model when the first one is down or rate limited.

How to configure OpenRouter API key?

Create a key on the OpenRouter keys page, then send it as Authorization: Bearer <key> (OpenRouter authentication docs, 2026). Store it in an environment variable such as OPENROUTER_API_KEY. For OpenAI SDKs, set the key as api_key and the base URL as https://openrouter.ai/api/v1.