# Use OpenRouter

> Get an OpenRouter key that reaches many models, connect it to Resurf, and know what to check when the connection test fails.

- Page: https://resurf.so/guides/use-openrouter
- Section: AI
- Works on: Mac, iPhone, iPad
- Last checked against the app: 2026-10-19
- Key from: openrouter.ai
- Looks like: sk-or-…
- Syncs: No, this device only

## Get a key

One OpenRouter key reaches models from many companies, paid from one balance. OpenRouter speaks OpenAI's API, so Resurf uses it as an OpenAI-compatible endpoint and checks each model it uses.

1. Sign in at [openrouter.ai](https://openrouter.ai/settings/keys) and open **Keys** under Settings.
2. Click **Create key** and name it. You can give the key a credit limit, or leave it unlimited. Copy the key: it starts with `sk-or-`.
3. Add credits on the **Credits** page before you connect. Models are paid from that balance. Models whose id ends in `:free` cost nothing but allow only a few dozen requests a day until you have bought credits, and stop when your balance goes negative.

On iPhone and iPad, the **Create a key at openrouter.ai** link on the key step opens the same page.

## Connect it

On Mac:

1. Choose **Settings…** (`⌘,`) and click **Providers** in the sidebar.
2. Click **Connect** beside **OpenRouter**.
3. Paste your key into **API key** and click **Connect**. Resurf sends one test request to check it.
4. OpenRouter moves to the top and shows **Connected**.

On iPhone and iPad:

1. In Resurf's Settings, turn on **AI**, or tap **Providers** if AI is already on.
2. Tap **OpenRouter**, paste your key and tap **Continue**.
3. Resurf checks the key. Then read what will be shared with OpenRouter and tap **Allow**.

![Settings, Providers pane: OpenAI and Gemini connected; Claude, OpenRouter and Ollama to connect.](https://resurf.so/guides/shots/settings-providers@2x.webp)

Your first provider turns on **AI features** and **Suggest as you capture**. The test sends your key and asks OpenRouter for its model list. Because OpenRouter lists models from many companies, Resurf may also send up to two short test prompts per feature to find ones that work, such as `Return {"ok": true}.` No capture content is in them.

## Pick a model that can do the job

Not every model on OpenRouter can do what Resurf asks of it, and OpenRouter's list doesn't say which can, so Resurf checks a model before it uses it.

| Feature | The model needs |
| --- | --- |
| Suggestions | Text and structured output. |
| Reading images | Vision as well. Without it, Resurf reads images with another vision model on OpenRouter, or organizes them from their text. |
| The Assistant on Mac | Streaming and tool calling. Vision is optional: images only go to a model that can see them. |

Pick a model in [Settings → AI → Model](https://resurf.so/guides/ai-model). If it fails the check, Mac says **This model is not ready for the selected feature.** A custom id that fails shows **Could not verify model**.

## What it powers in Resurf

Resurf picks an OpenRouter model for you when you connect. It writes [suggestions](https://resurf.so/guides/ai-suggestions) as you capture (titles, tags, spaces and summaries), voice note titles and clean-ups, generated notes, and answers in the [Assistant](https://resurf.so/guides/ask-ai) on Mac. If the model you pick can't see images, Resurf reads them with a vision model from OpenRouter, or organizes them from their text.

- **A model that is missing from the menus.** On Mac, click **Manage** beside OpenRouter, then **Add custom model…**, and enter its id as `vendor/model`. Resurf checks it for suggestions and the Assistant before it is offered.
- **Voice transcription stays where it was.** Cloud transcription is [OpenAI](https://resurf.so/guides/use-openai) only, so with OpenRouter alone, voice notes are transcribed on your device.
- **The key stays on this device.** OpenRouter keys don't sync, so connect OpenRouter on each Mac, iPhone and iPad you use.

## When the connection test fails

On Mac you see **Could not connect to OpenRouter. Check the API key and try again.** On iPhone and iPad the test step says **The key didn't work.**, with **Back** and **Try again**. A key that works in another app can still fail here: the test asks for the model list and may run short test prompts, and those cost a little credit.

| Likely cause | What to do |
| --- | --- |
| The key is wrong | A character is missing from the paste, or the key was deleted on openrouter.ai. Make a new key and paste the whole thing. |
| No credit | The test prompts need a balance above zero. Buy credits on the Credits page and try again. |
| The key's credit limit is reached | A key stops at the limit you set when you made it. Raise it on the key's page, or wait for a daily, weekly or monthly limit to reset. |

On Mac, click **Manage** beside OpenRouter and click **Test** to run the check again.

## Questions

### Why does Resurf send test prompts to OpenRouter?

OpenRouter's model list doesn't say which models can do what Resurf needs, so Resurf tries a short prompt, a small probe image and a one-tool call on candidate models. At most two per feature, with no capture content.

### Can I use any model on OpenRouter?

Any model that passes Resurf's check. Suggestions need structured output, images need vision, and the Assistant needs streaming and tool calling. A model without vision still works; images are then read by another vision model or from their text.

### Can I use the free models?

Yes, if Resurf picks one or you add it as a custom model. Free models have a daily request cap until you have bought credits, and stop when your balance is negative.

### Can I transcribe voice notes through OpenRouter?

No. Cloud transcription is OpenAI only. Voice notes are transcribed on your device otherwise.

## More guides

- Previous: [Use Gemini](https://resurf.so/guides/use-gemini.md)
- Next: [Run Ollama on your Mac](https://resurf.so/guides/ollama.md)
- [AI providers](https://resurf.so/guides/ai-providers.md): Connect your own AI provider with your own key. Resurf's AI features stay off until you do.
- [Use OpenAI](https://resurf.so/guides/use-openai.md): Get an OpenAI API key, connect it to Resurf, and know what to check when the connection test fails.
- [Use Claude](https://resurf.so/guides/use-claude.md): Get an Anthropic API key, connect it to Resurf, and know what to check when the connection test fails.
- [Use Gemini](https://resurf.so/guides/use-gemini.md): Get a Gemini API key from Google AI Studio, connect it to Resurf, and know what to check when the connection test fails.
- [Run Ollama on your Mac](https://resurf.so/guides/ollama.md): Run models on your own Mac with Ollama, with no key and nothing sent to the cloud.
- [AI suggestions](https://resurf.so/guides/ai-suggestions.md): When you save something, your AI provider writes a title, a summary and keywords for it, and suggests spaces.
- [Model and instructions](https://resurf.so/guides/ai-model.md): Pick the model that writes your suggestions, give it your own instructions, and run it again over your library.
- [Assistant](https://resurf.so/guides/ask-ai.md): Ask questions about your library in a chat pane on Mac, and get answers that cite the captures they used.
- [Voice notes and AI](https://resurf.so/guides/voice-ai.md): Transcribe voice notes on your device or with OpenAI, and let your model title them, tidy the transcript and write notes.
- [What AI sends](https://resurf.so/guides/ai-privacy.md): What each AI feature sends to your provider, and when nothing is sent at all.
- [Every guide](https://resurf.so/llms.txt)