How to Use OpenRouter Presets: Config-as-Code Guide
OpenRouter ·
You’ve put the same model name, system prompt, and temperature in a web app, a batch script, and a notebook. Now you want to change the temperature or model, so you have to edit all three.
We built presets to solve exactly this. A preset is config-as-code for your LLM calls, a named, versioned set of models, system prompts, provider routing, and sampling parameters. We let you define it once and use its name everywhere. When you change the preset, every app that uses it picks up the change.
This guide adds to the presets docs reference and the launch announcement. You’ll create a preset, use it in an API call, and work through two setups: an image-prompt-enhancement preset and a fixed Fusion configuration.
Tl;dr
- A preset stores a model or fallback array, a system prompt, provider routing, and sampling parameters under one name.
- Use it in any request as
"model": "@preset/your-preset-name". - Update it in the dashboard, and every app that uses it changes, no need for a code update.
What is an OpenRouter preset?
An OpenRouter preset is a named, versioned config that stores your model choices, a system prompt, provider routing preferences, and sampling parameters. We let you use it in any API request through its slug. This keeps your LLM setup out of your application code.
Think of a preset the way you would think of a .env file or a Terraform module, where a config lives outside your application logic and gets referenced by name rather than copied into it. The difference is where it lives and who can change it. A .env file still ships with your repo and needs a redeploy to update. We store the preset in the OpenRouter dashboard instead, so changing it immediately updates every app that references it.
- Model selection, one model or an ordered list of fallback models.
- System prompt, the instructions added before every request.
- Provider routing, sort by price or latency, and include or exclude providers.
- Sampling parameters, temperature,
top_p, and other settings. - Tools, including OpenRouter server tools such as web search, image generation, advisors, and subagents.
Preset vs. hardcoding your request body
| Hardcoded request | @preset/name | |
|---|---|---|
| Where config lives | In each codebase | Once in the dashboard |
| Change the system prompt | Edit and redeploy each app | Edit the preset; no redeploy |
| Model fallbacks | Repeat the array everywhere | Define it once in the preset |
| Who can change it | Anyone who can ship code | Anyone with dashboard access |
How to create your first preset
Step 1: Open the preset editor
Go to openrouter.ai/settings/presets and create a preset. Pick a slug you’ll remember, because you’ll use it as @preset/your-slug.
Step 2: Choose model and routing
Pick one model or add an ordered list. If the first model fails from a rate limit, outage, or too much context, we try the next one. You set the fallback order once in the preset instead of repeating it in every request.
Set provider routing here too, as seen in the screenshot above. You can sort by price or latency, or block a provider from your requests.
Step 3: Add a system prompt and sampling settings
Add your system prompt and set temperature, top_p, and any other sampling parameters. These become the defaults for every request that uses the preset.
Step 4: Reference it from an API call
Set the model field to your preset. Compare these requests.
Before, with every parameter in the request:
from openrouter import OpenRouter
client = OpenRouter(api_key=OPENROUTER_API_KEY)
resp = client.chat.send(
model="anthropic/claude-opus-4.8",
provider={"sort": "price"},
temperature=0.7,
messages=[
{"role": "system", "content": "You are a concise technical writer..."},
{"role": "user", "content": "Explain preset versioning."},
],
)After, with a preset reference:
resp = client.chat.send(
model="@preset/tech-writer",
messages=[
{"role": "user", "content": "Explain preset versioning."},
],
)You can also create a preset through the API with a POST request to the preset endpoint. We save the fields that belong to the preset config and ignore transient fields like messages, stream, and prompt.
curl https://openrouter.ai/api/v1/presets/tech-writer/chat/completions \
-H "Authorization: Bearer $OPENROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "anthropic/claude-opus-4.8",
"temperature": 0.7,
"messages": [
{"role": "system", "content": "You are a concise technical writer."}
]
}'You can override preset settings in each request. If the request body includes temperature, that value wins over the preset value. The merge is shallow, so request fields replace matching preset fields, and we keep any preset fields you leave out. tools is the exception: we combine the preset’s tools with the request’s tools, and a request tool replaces a preset tool with the same name. You can also use a separate preset field ("preset": "@preset/tech-writer") or the combined form ("model": "anthropic/claude-opus-4.8@preset/tech-writer"). The preset field needs the full @preset/ prefix. A bare slug is ignored.
Can you set a default preset?
Not for the API. Presets have versions. Saving an existing slug creates a new version and makes it active, but there is no global default preset for the API. Every request must name a preset. The Chatroom does have a Default Preset setting under Settings > Preferences that applies to new chat messages.
For the API, put your default behavior in a preset and use that preset everywhere. If you want short answers, add that rule to the preset’s system prompt (“Answer in three sentences or fewer unless asked to expand.”) and set the sampling parameters. Every service that uses @preset/short-answers will follow those defaults unless a request overrides them.
Using a preset by name gives you steady behavior you can change in one place. The same pattern extends to more complex setups. Here are two worked examples.
Use case 1: An image-prompt-enhancement preset
Image models often do better with detailed prompts. Instead of adding that detail by hand each time, pair a text model with the image-generation tool in a preset. The text model refines each prompt before it goes to the image model.
The preset stores a text model, a system prompt that turns a short request into a full visual brief covering subject, composition, lighting, palette, and style, and the image-generation tool.
curl https://openrouter.ai/api/v1/presets/image-enhancer/chat/completions \
-H "Authorization: Bearer $OPENROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "anthropic/claude-opus-4.8",
"messages": [
{"role": "system", "content": "You are an expert visual prompt engineer. Expand the user request into a detailed image prompt covering subject, composition, lighting, palette, and style, then call the image tool."}
],
"tools": [
{"type": "openrouter:image_generation",
"parameters": {"model": "google/gemini-3.1-flash-image"}}
],
"tool_choice": "required",
"temperature": 0.7
}'Once the preset is saved, test it directly in the Chatroom by opening the preset and selecting “Test in Chat.” Send a short prompt like “a cozy reading nook by a rainy window,” and the preset applies its system prompt and image tool. The text model expands your short prompt into a full visual brief, then calls the image tool automatically. Here’s what that looks like.
The preset stores the tools array and tool_choice along with the model, system prompt, and sampling parameters.
Every app that uses @preset/image-enhancer gets the same behavior. The preset-enhanced images cookbook walks through the full process.
Use case 2: Pinning a Fusion configuration as a preset
A Fusion setup runs a panel of models alongside your primary model, and the primary model writes the final answer using the panel’s outputs. Store the entire setup in a preset, then use it via a single reference.
Store the openrouter:fusion tool, with its analysis_models panel and analyst model, in the preset’s tools, then call @preset/fusion-panel from anywhere. Your web app, evaluation tools, and Slack bot all use the same panel. You adjust it in the dashboard instead of editing three codebases. For the exact fields a Fusion configuration uses and how the panel works, see the Fusion docs.
This also gives ML engineers a repeatable evaluation config with the same models, sampling settings, and routing under one stable slug.
Managing presets over time
Each time you save a preset with an existing slug, our system creates a new version and makes it active. API requests that use the preset get the active version.
Change the system prompt in the dashboard, and every app using that slug picks up the change on its next request. No redeploy. If the change hurts quality, restore an earlier version in the dashboard. New requests use it right away.
A product manager can change the system prompt or model in the dashboard without asking an engineer to edit code or ship a new build.
Presets across apps and teams
One preset can serve an API integration, a batch job, and a third-party app that supports the OpenAI-compatible API. Because presets use the standard model field, any client that can set a model string can use one.
For larger teams, a preset gives you one versioned place for model choices, routing, and prompts. It replaces constants scattered across several repos.
If you’re using an organization account, all members can access organization presets, which makes them a good way to share best practices across teams.
Conclusion
Three things to remember:
- A preset stores a model, system prompt, routing rules, and sampling settings under one name. Use it as
@preset/namein any request. - Updating a preset changes every app that uses it, with no redeploy. You can restore an earlier version if needed.
- The same shared config can power image-prompt enhancement and Fusion panels across many apps.
Create your first preset at openrouter.ai/settings/presets. Then try the preset-enhanced images cookbook.
Frequently Asked Questions
How do I change the model in OpenRouter?
Change the model in the preset at openrouter.ai/settings/presets. Every call that uses @preset/your-preset-name will use the new model on its next request. Without a preset, you have to change the model field in each request body.
What is OpenRouter model usage?
We give you one API endpoint for hundreds of models from Anthropic, OpenAI, Google, Meta, and other providers. Pick a model per request or use a preset, then pay each model’s token rate. See the models list for current options and prices.
What is the API limit for OpenRouter?
Rate limits vary by model and provider. A preset doesn’t change them. A preset only stores config, the model, prompt, routing, and sampling settings. The same limits apply whether you use a preset or put the parameters directly in each request. See the limits docs for current figures.
Is OpenRouter compatible with OpenAI?
Yes. We offer an OpenAI-compatible API. Presets use the standard model field, so any OpenAI SDK client can use them by setting "model": "@preset/your-preset-name".
Can a preset include fallback models?
Yes. A preset can hold an ordered list of models. If the first fails from a rate limit, outage, or too much context, we try the next one. You set the order once in the preset instead of in each request.
Can I override a preset’s settings per request?
Yes. Parameters in the request body win over preset values. The merge is shallow, so request fields replace matching preset fields, and we keep any preset fields you leave out. Tools are combined, with request tools replacing preset tools of the same name.
Do presets work through the API or only in the Chatroom?
Presets work through the OpenAI-compatible API. You can use @preset/slug in the model field, a separate preset field set to @preset/slug, or the combined model@preset/slug form.