
Chat with one of the many models hosted on OpenRouter
Source:R/provider-openrouter.R
chat_openrouter.RdSign up at https://openrouter.ai.
Support for features depends on the underlying model that you use; see
https://openrouter.ai/models for details. Use models_openrouter()
to list the available models along with their advertised token prices.
Arguments
- system_prompt
A system prompt to set the behavior of the assistant.
- api_key
- credentials
Override the default credentials. You generally should not need this argument; instead set the
OPENROUTER_API_KEYenvironment variable. The best place to set this is in.Renviron, which you can easily edit by callingusethis::edit_r_environ().If you do need additional control, this argument takes a zero-argument function that returns either a string (the API key), or a named list (added as additional headers to every request).
- model
The model to use for the chat (defaults to "gpt-6.1-terra"). We regularly update the default, so we strongly recommend explicitly specifying a model for anything other than casual use.
- params
Common model parameters, usually created by
params().- api_args
Named list of arbitrary extra arguments appended to the body of every chat API call. Combined with the body object generated by ellmer with
modifyList().- echo
One of the following options:
none: don't emit any output (default when running in a function).output: echo text and tool-calling output as it streams in (default when running at the console).all: echo all input and output.
Note this only affects the
chat()method.- api_headers
Named character vector of arbitrary extra headers appended to every chat API call.
- strict
If
TRUE, use OpenAI's strict mode for tool definitions and structured output. Only set this if the endpoint and model support it.- base_url
The base URL of the OpenRouter API. The
/modelsendpoint used bymodels_openrouter()is public, so no credentials are required.
Value
chat_openrouter() returns a Chat object. models_openrouter()
returns a data frame with one row per model, with its id, created_at,
human-readable name, and context_length, plus the cached_input,
input, and output prices OpenRouter advertises, in US dollars per
million tokens. An NA price means that specific rate is unknown, e.g.
because the model's cost is set by the underlying provider at request
time; genuinely free models report 0.
Cost reporting
OpenRouter's reported request cost is used when available, including zero.
If no valid charge is reported, ellmer estimates from advertised token
rates when both prompt and completion counts and the required rates are
available. Otherwise, the cost is unknown (NA), not zero.
Estimates cover token rates only and may differ from the final routed charge. Rates are cached for the session and may become stale. The first fallback lookup is synchronous and may pause even an asynchronous chat. See the OpenRouter usage accounting documentation.
An unknown turn cost makes cumulative chat and model totals unknown, while known individual turn costs remain available. With a provider key configured in OpenRouter (BYOK), the reported cost is OpenRouter's charge; the provider may bill you separately.
See also
Other chatbots:
chat_anthropic(),
chat_aws_bedrock(),
chat_azure_openai(),
chat_cloudflare(),
chat_databricks(),
chat_deepseek(),
chat_github(),
chat_google_gemini(),
chat_groq(),
chat_huggingface(),
chat_lmstudio(),
chat_mistral(),
chat_ollama(),
chat_openai(),
chat_openai_compatible(),
chat_perplexity(),
chat_portkey(),
chat_posit()