# OpenRouter

Message models from many providers through one OpenRouter key, with fallbacks, provider routing and web search; create embeddings; check costs and credit.

## Connect OpenRouter

1. In the sidebar, open **Connections** and press **Add connection**.
2. Type `openrouter` and choose **OpenRouter**.
3. Fill in the fields. Each one says **Required** or **Optional**.
4. Press **Test and save**. GoRunner checks the connection before it saves anything.

The sheet asks for:

- **API Key · Required**: An OpenRouter API key (sk-or-…).

Paste an OpenRouter API key: openrouter.ai → Settings → API Keys → Create Key.

[Connections](https://docs.gorunner.io/build/connections) says how to sign in again, rename or delete it. In a product that embeds GoRunner, **Add connection** can be missing: then [your provider makes connections](https://docs.gorunner.io/embed/customer-connections) for you.

## Do things in OpenRouter

Add an **OpenRouter** step, choose a **Resource**, then an **Operation**. Choose a row to see its fields.

- [Text](https://docs.gorunner.io/apps/openrouter#fields-f-text): Message a Model
- [Image](https://docs.gorunner.io/apps/openrouter#fields-f-image): Analyze Image
- [Embedding](https://docs.gorunner.io/apps/openrouter#fields-f-embedding): Create Embeddings
- [Model](https://docs.gorunner.io/apps/openrouter#fields-f-model): Get Many
- [Generation](https://docs.gorunner.io/apps/openrouter#fields-f-generation): Get Stats
- [Account](https://docs.gorunner.io/apps/openrouter#fields-f-account): Get Key Usage · Get Credits

To start a workflow from OpenRouter, use a [Schedule](https://docs.gorunner.io/apps/schedule), [Webhook](https://docs.gorunner.io/apps/webhook) or [Form](https://docs.gorunner.io/apps/form) trigger.

Later steps read a step’s output by its name: see [Use data from earlier steps](https://docs.gorunner.io/build/use-data-from-earlier-steps).

## Limits

- A reply from OpenRouter can be up to 16 MB (a file download can have its own limit). A larger one fails the step; it is never cut short.
- When OpenRouter says to slow down (429), the step waits as long as it asks, if the step’s time allows. Otherwise it fails and says when to try again.

Not in your list? See [When an app isn’t here](https://docs.gorunner.io/apps/when-an-app-isnt-here#q-not-in-list).

## For developers

In the API, which calls apps pieces, OpenRouter is `pieceId: "openrouter"` with `actionId: "openrouter"`, set by `resource` and an `operation_…` field, such as `operation_account`. [Get an app](https://docs.gorunner.io/api/apps/get-app) returns every field.

It reads from outside without changing anything (`reads_external`). See [How versions and side effects work](https://docs.gorunner.io/apps#q-versions).

### OpenRouter › Text

### Message a Model

- **Model · Required**: The model that answers, as provider/model (such as anthropic/claude-sonnet-4.5), or openrouter/auto to let OpenRouter choose.
- **Prompt · Required**: What to ask or tell the model.
- **System Message · Optional**: Standing instructions for the model: its role, tone and rules. Optional.
- **Earlier Messages · Optional**: Earlier turns of the conversation, oldest first, sent before the prompt: [{"role":"user","content":"…"},{"role":"assistant","content":"…"}].
- **Fallback Models · Optional**: Models to try, in order, when the first is down, rate-limited or refuses the request: one per line (at most 3 beside the model).
- **Prefer Providers By · Optional**: Which of the model's providers to try first. Default balances price and uptime. Options: Default, Lowest price, Highest throughput, Lowest latency. Default: Default.
- **Provider Order · Optional**: Provider slugs to try in this order, comma-separated (as on the model's page on openrouter.ai). Empty lets OpenRouter choose.
- **Allow Other Providers · Optional**: Let OpenRouter use providers outside Provider Order when those fail. Off: only the listed ones. On by default.
- **Data Collection · Optional**: Deny skips providers that may store or train on prompts. Default follows the account's privacy settings. Options: Default, Allow, Deny. Default: Default.
- **Zero Data Retention Only · Optional**: Use only endpoints that keep no prompts or answers. Off by default.
- **Reasoning Effort · Optional**: How hard a reasoning model thinks before it answers. Models without reasoning ignore it. Options: Default, None, Minimal, Low, Medium, High, Extra high. Default: Default.
- **Web Search · Optional**: Ground the answer in web results (OpenRouter's web plugin, billed per search); the pages cited come back in citations. Off by default.
- **Web Results · Optional**: How many web results to give the model (1–10). Empty uses OpenRouter's default. Shows when **Web Search** is on.
- **Output Format · Optional**: Text, or JSON the step parses for later steps (under json). For a JSON object, say in the prompt what the JSON should hold. Options: Text, JSON object, JSON matching a schema. Default: Text.
- **JSON Schema · Required**: The JSON Schema the answer must match, such as {"type":"object","properties":{"city":{"type":"string"}},"required":["city"]}. Shows when **Output Format** is **JSON matching a schema**.
- **Max Tokens · Optional**: The most tokens the answer may use (reasoning included on reasoning models). Empty uses the model's default.
- **Temperature · Optional**: 0–2: lower is more focused and repeatable, higher more varied. Empty uses the model's default.
- **Top P · Optional**: 0–1: sample only from the most likely tokens whose probabilities add up to this. Change this or Temperature, not both.
- **Stop Sequences · Optional**: Text that ends the answer when the model writes it, one per line (at most 4).
- **Tools · Optional**: Functions the model may ask to call, as a list: [{"type":"function","function":{"name":"get_weather","description":"…","parameters":{…}}}]. The calls it asks for are in tool_calls; this step does not call them.
- **More Options · Optional**: Other request fields OpenRouter documents for chat completions, as JSON (such as {"seed": 7}). They are added to the request as written.

### OpenRouter › Image

### Analyze Image

- **Model · Required**: A model that reads images.
- **Question · Required**: What to ask about the images.
- **System Message · Optional**: Standing instructions for the model: its role, tone and rules. Optional.
- **Earlier Messages · Optional**: Earlier turns of the conversation, oldest first, sent before the prompt: [{"role":"user","content":"…"},{"role":"assistant","content":"…"}].
- **Image URLs · Optional**: Links to the images, one per line (https:// or data: URLs). OpenRouter passes them to the model's provider.
- **Image File · Optional**: Upload a file, or switch to an expression to use one from an earlier step (such as {{steps.download.result}}). JPEG, PNG, GIF or WebP. Use this, Image URLs, or both.
- **Fallback Models · Optional**: Models to try, in order, when the first is down, rate-limited or refuses the request: one per line (at most 3 beside the model).
- **Prefer Providers By · Optional**: Which of the model's providers to try first. Default balances price and uptime. Options: Default, Lowest price, Highest throughput, Lowest latency. Default: Default.
- **Provider Order · Optional**: Provider slugs to try in this order, comma-separated (as on the model's page on openrouter.ai). Empty lets OpenRouter choose.
- **Allow Other Providers · Optional**: Let OpenRouter use providers outside Provider Order when those fail. Off: only the listed ones. On by default.
- **Data Collection · Optional**: Deny skips providers that may store or train on prompts. Default follows the account's privacy settings. Options: Default, Allow, Deny. Default: Default.
- **Zero Data Retention Only · Optional**: Use only endpoints that keep no prompts or answers. Off by default.
- **Reasoning Effort · Optional**: How hard a reasoning model thinks before it answers. Models without reasoning ignore it. Options: Default, None, Minimal, Low, Medium, High, Extra high. Default: Default.
- **Web Search · Optional**: Ground the answer in web results (OpenRouter's web plugin, billed per search); the pages cited come back in citations. Off by default.
- **Web Results · Optional**: How many web results to give the model (1–10). Empty uses OpenRouter's default. Shows when **Web Search** is on.
- **Output Format · Optional**: Text, or JSON the step parses for later steps (under json). For a JSON object, say in the prompt what the JSON should hold. Options: Text, JSON object, JSON matching a schema. Default: Text.
- **JSON Schema · Required**: The JSON Schema the answer must match, such as {"type":"object","properties":{"city":{"type":"string"}},"required":["city"]}. Shows when **Output Format** is **JSON matching a schema**.
- **Max Tokens · Optional**: The most tokens the answer may use (reasoning included on reasoning models). Empty uses the model's default.
- **Temperature · Optional**: 0–2: lower is more focused and repeatable, higher more varied. Empty uses the model's default.
- **Top P · Optional**: 0–1: sample only from the most likely tokens whose probabilities add up to this. Change this or Temperature, not both.
- **Stop Sequences · Optional**: Text that ends the answer when the model writes it, one per line (at most 4).
- **More Options · Optional**: Other request fields OpenRouter documents for chat completions, as JSON (such as {"seed": 7}). They are added to the request as written.

### OpenRouter › Embedding

### Create Embeddings

- **Model · Required**: An embedding model (such as openai/text-embedding-3-small).
- **Texts · Required**: The text to embed, or a list of texts from an earlier step (one vector per text, at most 2048).
- **Dimensions · Optional**: How many numbers each vector has, for models that can shorten theirs. Empty uses the model's size.

### OpenRouter › Model

### Get Many

- **Search · Optional**: Text in the model's name or id. Empty lists every model of the kind below.
- **Kind · Optional**: Which models to list, by what they produce. Options: Text, Images, Embeddings, Audio, All. Default: Text.
- **Return All · Optional**: Read every model, page by page (at most 1000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many models to return (1–1000). Default: 100. Shows when **Return All** is off.

### OpenRouter › Generation

### Get Stats

- **Generation ID · Required**: The id a Message or Embeddings step returned (its id, gen-…).

### OpenRouter › Account

### Get Key Usage and Get Credits

Nothing to fill in.

Source: https://docs.gorunner.io/apps/openrouter