Genesis Docs

OpenRouter provides a unified API that routes requests to many models behind a single endpoint and API key. It is OpenAI-compatible, so most OpenAI SDKs work by switching the base URL.

Getting started

Get your API key

Create an API key at [openrouter.ai/keys](https://openrouter.ai/keys).

Run onboarding

```bash
genesis onboard --auth-choice openrouter-api-key
```

(Optional) Switch to a specific model

Onboarding defaults to `openrouter/auto`. Pick a concrete model later:

```bash
genesis models set openrouter/<provider>/<model>
```

Config example

{
  env: { OPENROUTER_API_KEY: "sk-or-..." },
  agents: {
    defaults: {
      model: { primary: "openrouter/auto" },
    },
  },
}

Model references

Model refs follow the pattern `openrouter//`. For the full list of available providers and models, see [/concepts/model-providers](/concepts/model-providers).

Bundled fallback examples:

Model ref Notes
openrouter/auto OpenRouter automatic routing
openrouter/moonshotai/kimi-k2.6 Kimi K2.6 via MoonshotAI
openrouter/openrouter/healer-alpha OpenRouter Healer Alpha route
openrouter/openrouter/hunter-alpha OpenRouter Hunter Alpha route

Image generation

OpenRouter can also back the image_generate tool. Use an OpenRouter image model under agents.defaults.imageGenerationModel:

{
  env: { OPENROUTER_API_KEY: "sk-or-..." },
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "openrouter/google/gemini-3.1-flash-image-preview",
      },
    },
  },
}

Genesis sends image requests to OpenRouter's chat completions image API with modalities: ["image", "text"]. Gemini image models receive supported aspectRatio and resolution hints through OpenRouter's image_config.

Text-to-speech

OpenRouter can also be used as a TTS provider through its OpenAI-compatible /audio/speech endpoint.

{
  messages: {
    tts: {
      auto: "always",
      provider: "openrouter",
      providers: {
        openrouter: {
          model: "hexgrad/kokoro-82m",
          voice: "af_alloy",
          responseFormat: "mp3",
        },
      },
    },
  },
}

If messages.tts.providers.openrouter.apiKey is omitted, TTS reuses models.providers.openrouter.apiKey, then OPENROUTER_API_KEY.

Authentication and headers

OpenRouter uses a Bearer token with your API key under the hood.

On real OpenRouter requests (https://openrouter.ai/api/v1), Genesis also adds OpenRouter's documented app-attribution headers:

Header Value
HTTP-Referer https://genesis.pixelzx.com
X-OpenRouter-Title Genesis
X-OpenRouter-Categories cli-agent
If you repoint the OpenRouter provider at some other proxy or base URL, Genesis does **not** inject those OpenRouter-specific headers or Anthropic cache markers.

Advanced configuration

Anthropic cache markers

On verified OpenRouter routes, Anthropic model refs keep the
OpenRouter-specific Anthropic `cache_control` markers that Genesis uses for
better prompt-cache reuse on system/developer prompt blocks.

Thinking / reasoning injection

On supported non-`auto` routes, Genesis maps the selected thinking level to
OpenRouter proxy reasoning payloads. Unsupported model hints and
`openrouter/auto` skip that reasoning injection.

OpenAI-only request shaping

OpenRouter still runs through the proxy-style OpenAI-compatible path, so
native OpenAI-only request shaping such as `serviceTier`, Responses `store`,
OpenAI reasoning-compat payloads, and prompt-cache hints is not forwarded.

Gemini-backed routes

Gemini-backed OpenRouter refs stay on the proxy-Gemini path: Genesis keeps
Gemini thought-signature sanitation there, but does not enable native Gemini
replay validation or bootstrap rewrites.

Provider routing metadata

If you pass OpenRouter provider routing under model params, Genesis forwards
it as OpenRouter routing metadata before the shared stream wrappers run.

Related