# OpenRouter API relay for AI agents and apps (`artogahr/openrouter-relay`) Actor

Use OpenRouter models in compatible AI agents and apps with your Apify account.

- **URL**: https://apify.com/artogahr/openrouter-relay.md
- **Developed by:** [Arto Gahr](https://apify.com/artogahr) (community)
- **Categories:** Developer tools
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-usage

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

### Use OpenRouter models in compatible AI agents and apps

This Actor lets an AI agent or app use OpenRouter models with an Apify API token. It forwards supported API requests to [Apify's OpenRouter Actor](https://apify.com/apify/openrouter) and streams the response back. The models run remotely; you do not need a local GPU.

Use the Standby URL in a client that supports a custom OpenAI-compatible or Anthropic-format API endpoint. There is no Actor input to configure. Apify starts a separate Standby run for each caller and injects that caller's `APIFY_TOKEN`; the relay uses it for the upstream request. Your prompts, tool results, and any file content your client sends go to the selected model provider through OpenRouter.

#### Supported API routes

| Method | Path | Purpose |
| --- | --- | --- |
| POST | `/api/v1/chat/completions` | OpenAI chat completions, including streaming |
| POST | `/api/v1/responses` | OpenAI Responses API, including streaming |
| POST | `/api/v1/messages` | Anthropic-format messages, including streaming |
| GET | `/api/v1/models` | List models available through the upstream Actor |

The relay passes JSON bodies and model IDs through unchanged. It replaces the caller's authorization with the Standby run token. Other routes return `404`. Upstream errors and rate limits reach the client with their status codes.

### Connect an agent or app

Set the client's API base URL to `https://artogahr--openrouter-relay.apify.actor/api/v1`. For a client that asks for the full endpoint instead, use one of the paths above. Set its API key or bearer token to **your Apify API token**, and choose a model ID from `/api/v1/models`. The client must support at least one of the listed API routes; changing only the base URL cannot make an unsupported API format work.

Use the [Endpoints tab](https://apify.com/artogahr/openrouter-relay) to inspect and try requests in a browser. If your client can run a command to obtain its API key, `apify auth token` avoids storing the token in its config. Otherwise, use your client's secret storage or an environment variable. Do not put an Apify token in a shared config file.

For one tested client configuration, see the [Pi example](https://github.com/artogahr/openrouter-relay/blob/main/examples/pi.md). The same base URL and token work for other clients that let you configure a compatible API provider.

### Send an HTTP request

```sh
APIFY_TOKEN=$(apify auth token)
curl 'https://artogahr--openrouter-relay.apify.actor/api/v1/chat/completions' \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"model":"openrouter/auto","messages":[{"role":"user","content":"Hello"}],"stream":true}'
```

The response is the upstream JSON response or server-sent event stream. For example, a non-streaming chat response contains `choices[0].message.content`. Starting the Actor as a normal Console run checks the upstream model catalog and writes one diagnostic dataset item; it does not start the HTTP relay.

### Pricing and limits

Each caller pays for their own Standby run's Apify compute and for model use charged by `apify/openrouter`. This relay adds no pay-per-event charge. The Standby run stops after its idle timeout, so an occasional request may wait for a new run to start. Check the [upstream pricing and limits](https://apify.com/apify/openrouter) before choosing a model. In particular, its Chat and Responses routes currently cap output at 2,048 tokens. Model availability and provider limits can change.

### Troubleshooting and support

- `401` or `403`: check that your client sends an Apify API token to the Standby URL. Check whether the client has another saved credential that overrides your config.
- `404`: use one of the four supported paths above and include `/api/v1` in the base URL.
- `429` or another upstream error: inspect the response body and your Apify usage limits. The relay preserves upstream status codes.
- A long first request: Apify may be starting a Standby run. Later requests to an active run should avoid that startup wait.

For a relay bug or integration question, [open a GitHub issue](https://github.com/artogahr/openrouter-relay/issues). For Apify account or billing questions, use [Apify support](https://help.apify.com/).

### Develop

The [source code](https://github.com/artogahr/openrouter-relay) is MIT-licensed and packaged as a standalone Nix flake. Run `nix develop`, then `cargo test --locked` and `cargo clippy --all-targets -- -D warnings`. Run `nix build` to build with Nix. Tests use a local mock upstream and spend no model tokens. Pushes to `main` run Rust checks in GitHub Actions and start an Apify build from this repository.

# Actor input Schema

## Actor input object example

```json
{}
```

# Actor output Schema

## `diagnostic` (type: `string`):

A standard run checks that the upstream model catalog is available.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("artogahr/openrouter-relay").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("artogahr/openrouter-relay").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call artogahr/openrouter-relay --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,artogahr/openrouter-relay"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/VA2y8ch26ZPTST4eH/builds/P4ISwvDhQKbdgu4gg/openapi.json