@ottervoice/provider-openrouter

Documentation / @ottervoice/provider-openrouter

@ottervoice/provider-openrouter

OpenRouter providers for OtterVoice: text LLM, audio LLM, speech-to-text, and text-to-speech through OpenAI-compatible APIs.

Install

npm install @ottervoice/core @ottervoice/provider-openrouter

Usage

import { createOpenRouterLLM } from '@ottervoice/provider-openrouter';

const llm = createOpenRouterLLM({
  model: 'openai/gpt-4o-mini',
  tokenBrokerUrl: '/api/voice-token',
});

Use tokenBrokerUrl in browser and mobile apps so OpenRouter credentials remain on your server. The package also exports audio LLM, ASR, and TTS provider factories.

Links

Documentation · GitHub

License

MIT

Interfaces

ChatBody

Defined in: provider-openrouter/src/chat.ts:7

OpenAI-compatible chat-completions request body fields used by the adapter.

Properties

Property	Type	Description	Defined in
`max_tokens?`	`number`	Max completion tokens.	provider-openrouter/src/chat.ts:15
`messages`	{ `content`: `string`; `role`: `string`; }[]	Chat messages in OpenAI role/content shape.	provider-openrouter/src/chat.ts:11
`model`	`string`	Model id on OpenRouter.	provider-openrouter/src/chat.ts:9
`reasoning?`	{ `enabled`: `boolean`; }	OpenRouter reasoning toggle when the model supports it.	provider-openrouter/src/chat.ts:21
`reasoning.enabled`	`boolean`	-	provider-openrouter/src/chat.ts:21
`response_format?`	{ `type`: `"json_object"`; }	Force JSON-object responses when supported.	provider-openrouter/src/chat.ts:19
`response_format.type`	`"json_object"`	-	provider-openrouter/src/chat.ts:19
`stream?`	`boolean`	When true, request SSE streaming.	provider-openrouter/src/chat.ts:17
`temperature?`	`number`	Sampling temperature.	provider-openrouter/src/chat.ts:13

HeaderOptions

Defined in: provider-openrouter/src/chat.ts:57

Optional OpenRouter attribution and header overrides.

Extended by

Properties

Property	Type	Description	Defined in
`headers?`	`Record`<`string`, `string`>	Extra headers merged last (override defaults carefully).	provider-openrouter/src/chat.ts:63
`referer?`	`string`	Sent as `HTTP-Referer` for OpenRouter rankings / allowlists.	provider-openrouter/src/chat.ts:59
`title?`	`string`	Sent as `X-Title` (app name shown on OpenRouter).	provider-openrouter/src/chat.ts:61

OpenRouterASROptions

Defined in: provider-openrouter/src/audio.ts:22

Options for OpenRouter HTTP transcription (batch / rolling partial ASR).

Extends

CredentialOptions.HeaderOptions

Properties

Property	Type	Description	Overrides	Inherited from	Defined in
`apiKey?`	`string`	A long-lived key (server-side only — never ship to clients).	-	`CredentialOptions`.`apiKey`	provider-utils/dist/credential.d.ts:35
`baseUrl?`	`string`	API root; defaults to OpenRouter’s chat-compatible base URL.	-	-	provider-openrouter/src/audio.ts:40
`emptyPartialBackoffMs?`	`number`	Delay the next rolling request after an empty provisional transcript. Defaults to the greater of 3x `partialIntervalMs` and 3 seconds.	-	-	provider-openrouter/src/audio.ts:36
`fetch?`	`FetchLike`	Custom `fetch` implementation (tests / React Native polyfills).	-	`CredentialOptions`.`fetch`	provider-utils/dist/credential.d.ts:39
`format?`	`"opus"` \| `"webm"` \| `"wav"` \| `"mp3"`	Browser MediaRecorder defaults to WebM.	-	-	provider-openrouter/src/audio.ts:26
`headers?`	`Record`<`string`, `string`>	Extra headers merged last (override defaults carefully).	-	`HeaderOptions`.`headers`	provider-openrouter/src/chat.ts:63
`language?`	`string`	BCP-47 language hint sent to the transcription API when supported.	-	-	provider-openrouter/src/audio.ts:38
`model`	`string`	OpenRouter / OpenAI-compatible transcription model id.	-	-	provider-openrouter/src/audio.ts:24
`now?`	() => `number`	Test hook for partial-result scheduling.	`CredentialOptions`.`now`	-	provider-openrouter/src/audio.ts:42
`partialIntervalMs?`	`number`	Re-transcribe the accumulated live PCM at this interval to provide best-effort partial results before the turn ends. Omit for batch-only ASR.	-	-	provider-openrouter/src/audio.ts:31
`referer?`	`string`	Sent as `HTTP-Referer` for OpenRouter rankings / allowlists.	-	`HeaderOptions`.`referer`	provider-openrouter/src/chat.ts:59
`title?`	`string`	Sent as `X-Title` (app name shown on OpenRouter).	-	`HeaderOptions`.`title`	provider-openrouter/src/chat.ts:61
`tokenBrokerUrl?`	`string`	Endpoint that mints short-lived tokens (client-safe).	-	`CredentialOptions`.`tokenBrokerUrl`	provider-utils/dist/credential.d.ts:37

OpenRouterAudioLLMOptions

Defined in: provider-openrouter/src/audio-llm.ts:30

Options for the OpenRouter Audio LLM adapter (pipeline: 'audio_llm').

Extends

CredentialOptions.HeaderOptions

Properties

Property	Type	Description	Inherited from	Defined in
`apiKey?`	`string`	A long-lived key (server-side only — never ship to clients).	`CredentialOptions`.`apiKey`	provider-utils/dist/credential.d.ts:35
`baseUrl?`	`string`	API root; defaults to OpenRouter’s public `…/api/v1`.	-	provider-openrouter/src/audio-llm.ts:36
`defaultTemperature?`	`number`	Default sampling temperature when the session does not override.	-	provider-openrouter/src/audio-llm.ts:38
`fetch?`	`FetchLike`	Custom `fetch` implementation (tests / React Native polyfills).	`CredentialOptions`.`fetch`	provider-utils/dist/credential.d.ts:39
`headers?`	`Record`<`string`, `string`>	Extra headers merged last (override defaults carefully).	`HeaderOptions`.`headers`	provider-openrouter/src/chat.ts:63
`model`	`string`	Audio-capable chat model id (e.g. OpenAI GPT-4o-audio via OpenRouter).	-	provider-openrouter/src/audio-llm.ts:32
`now?`	() => `number`	Clock override for deterministic expiry checks in tests.	`CredentialOptions`.`now`	provider-utils/dist/credential.d.ts:41
`prepareAudio?`	(`audio`, `format`) => `Promise`<`PreparedAudioInput`>	OpenAI audio chat accepts WAV/MP3, while browsers normally record WebM. Supply a runtime-specific decoder when WebM/Opus input is possible.	-	provider-openrouter/src/audio-llm.ts:43
`referer?`	`string`	Sent as `HTTP-Referer` for OpenRouter rankings / allowlists.	`HeaderOptions`.`referer`	provider-openrouter/src/chat.ts:59
`title?`	`string`	Sent as `X-Title` (app name shown on OpenRouter).	`HeaderOptions`.`title`	provider-openrouter/src/chat.ts:61
`tokenBrokerUrl?`	`string`	Endpoint that mints short-lived tokens (client-safe).	`CredentialOptions`.`tokenBrokerUrl`	provider-utils/dist/credential.d.ts:37
`voice?`	\| `"alloy"` \| `"ash"` \| `"ballad"` \| `"coral"` \| `"echo"` \| `"fable"` \| `"nova"` \| `"onyx"` \| `"sage"` \| `"shimmer"` \| `"verse"`	Output voice when the model returns spoken audio.	-	provider-openrouter/src/audio-llm.ts:34

OpenRouterOptions

Defined in: provider-openrouter/src/index.ts:34

Options for createOpenRouterLLM. Extends CredentialOptions and HeaderOptions; prefer tokenBrokerUrl on clients over a static apiKey.

Extends

CredentialOptions.HeaderOptions

Properties

Property	Type	Description	Inherited from	Defined in
`apiKey?`	`string`	A long-lived key (server-side only — never ship to clients).	`CredentialOptions`.`apiKey`	provider-utils/dist/credential.d.ts:35
`baseUrl?`	`string`	API base, default `https://openrouter.ai/api/v1`.	-	provider-openrouter/src/index.ts:38
`defaultTemperature?`	`number`	Applied when a request does not specify its own temperature.	-	provider-openrouter/src/index.ts:40
`fetch?`	`FetchLike`	Custom `fetch` implementation (tests / React Native polyfills).	`CredentialOptions`.`fetch`	provider-utils/dist/credential.d.ts:39
`headers?`	`Record`<`string`, `string`>	Extra headers merged last (override defaults carefully).	`HeaderOptions`.`headers`	provider-openrouter/src/chat.ts:63
`model`	`string`	OpenRouter model id, e.g. `openai/gpt-4o-mini`.	-	provider-openrouter/src/index.ts:36
`now?`	() => `number`	Clock override for deterministic expiry checks in tests.	`CredentialOptions`.`now`	provider-utils/dist/credential.d.ts:41
`reasoningEnabled?`	`boolean`	Explicitly enable/disable reasoning tokens on compatible models.	-	provider-openrouter/src/index.ts:42
`referer?`	`string`	Sent as `HTTP-Referer` for OpenRouter rankings / allowlists.	`HeaderOptions`.`referer`	provider-openrouter/src/chat.ts:59
`title?`	`string`	Sent as `X-Title` (app name shown on OpenRouter).	`HeaderOptions`.`title`	provider-openrouter/src/chat.ts:61
`tokenBrokerUrl?`	`string`	Endpoint that mints short-lived tokens (client-safe).	`CredentialOptions`.`tokenBrokerUrl`	provider-utils/dist/credential.d.ts:37

OpenRouterTTSOptions

Defined in: provider-openrouter/src/audio.ts:46

Options for OpenRouter HTTP speech synthesis.

Extends

CredentialOptions.HeaderOptions

Properties

Property	Type	Description	Inherited from	Defined in
`apiKey?`	`string`	A long-lived key (server-side only — never ship to clients).	`CredentialOptions`.`apiKey`	provider-utils/dist/credential.d.ts:35
`baseUrl?`	`string`	API root; defaults to OpenRouter’s chat-compatible base URL.	-	provider-openrouter/src/audio.ts:52
`fetch?`	`FetchLike`	Custom `fetch` implementation (tests / React Native polyfills).	`CredentialOptions`.`fetch`	provider-utils/dist/credential.d.ts:39
`headers?`	`Record`<`string`, `string`>	Extra headers merged last (override defaults carefully).	`HeaderOptions`.`headers`	provider-openrouter/src/chat.ts:63
`model`	`string`	OpenRouter / OpenAI-compatible TTS model id.	-	provider-openrouter/src/audio.ts:48
`now?`	() => `number`	Clock override for deterministic expiry checks in tests.	`CredentialOptions`.`now`	provider-utils/dist/credential.d.ts:41
`referer?`	`string`	Sent as `HTTP-Referer` for OpenRouter rankings / allowlists.	`HeaderOptions`.`referer`	provider-openrouter/src/chat.ts:59
`speed?`	`number`	Speaking rate multiplier when the upstream model supports it.	-	provider-openrouter/src/audio.ts:54
`title?`	`string`	Sent as `X-Title` (app name shown on OpenRouter).	`HeaderOptions`.`title`	provider-openrouter/src/chat.ts:61
`tokenBrokerUrl?`	`string`	Endpoint that mints short-lived tokens (client-safe).	`CredentialOptions`.`tokenBrokerUrl`	provider-utils/dist/credential.d.ts:37
`voice`	`string`	Voice name accepted by the selected model.	-	provider-openrouter/src/audio.ts:50

PreparedAudioInput

Defined in: provider-openrouter/src/audio-llm.ts:22

WAV/MP3 bytes ready for OpenAI-compatible audio chat.

Properties

Property	Type	Description	Defined in
`audio`	`ArrayBuffer`	Encoded audio body.	provider-openrouter/src/audio-llm.ts:24
`format`	`"wav"` \| `"mp3"`	Container accepted by the audio chat API.	provider-openrouter/src/audio-llm.ts:26

Variables

DEFAULT_BASE_URL

const DEFAULT_BASE_URL: "https://openrouter.ai/api/v1" = 'https://openrouter.ai/api/v1';

Defined in: provider-openrouter/src/chat.ts:4

Default OpenRouter OpenAI-compatible API root.

Functions

buildChatBody()

function buildChatBody(
   model,
   input,
   defaults?,
   openRouter?): ChatBody;

Defined in: provider-openrouter/src/chat.ts:32

Build the OpenAI-compatible chat-completions request body.

Parameters

Parameter	Type	Description
`model`	`string`	OpenRouter model id.
`input`	`LLMGenerateInput`	Core LLMGenerateInput messages and knobs.
`defaults`	{ `stream?`: `boolean`; `temperature?`: `number`; }	Adapter-level temperature / stream defaults.
`defaults.stream?`	`boolean`	-
`defaults.temperature?`	`number`	-
`openRouter`	{ `reasoningEnabled?`: `boolean`; }	OpenRouter-specific extras (e.g. reasoning).
`openRouter.reasoningEnabled?`	`boolean`	-

Returns

ChatBody

buildHeaders()

function buildHeaders(token, options): Record<string, string>;

Defined in: provider-openrouter/src/chat.ts:72

Assemble request headers, including OpenRouter’s optional attribution.

Parameters

Parameter	Type	Description
`token`	`string`	Bearer token from apiKey or token broker.
`options`	`HeaderOptions`	Attribution and header overrides.

Returns

Record<string, string>

bytesToBase64()

function bytesToBase64(bytes): string;

Defined in: provider-openrouter/src/audio.ts:148

Browser- and Node-safe base64 without relying on Buffer.

Parameters

Parameter	Type
`bytes`	`Uint8Array`

Returns

string

createOpenRouterASR()

function createOpenRouterASR(options): ASRProvider;

Defined in: provider-openrouter/src/audio.ts:173

Transcription through OpenRouter’s /audio/transcriptions endpoint. The default remains one request at turn end. Setting partialIntervalMs adds rolling, best-effort snapshots for low-latency partial text while the final request still covers the complete turn.

Parameters

Parameter	Type	Description
`options`	`OpenRouterASROptions`	Model, credentials, and optional rolling-partial interval.

Returns

ASRProvider

An ASRProvider for VoiceSessionConfig.providers.asr.

createOpenRouterAudioLLM()

function createOpenRouterAudioLLM(options): AudioLLMProvider;

Defined in: provider-openrouter/src/audio-llm.ts:163

OpenRouter chat-completions adapter for models such as openai/gpt-audio-mini that understand speech and generate speech directly.

Parameters

Parameter	Type	Description
`options`	`OpenRouterAudioLLMOptions`	Model, voice, credentials, and optional WebM→WAV preparer.

Returns

AudioLLMProvider

An AudioLLMProvider for pipeline: 'audio_llm'.

createOpenRouterLLM()

function createOpenRouterLLM(options): LLMProvider;

Defined in: provider-openrouter/src/index.ts:53

LLM provider backed by OpenRouter’s OpenAI-compatible HTTP API. Credentials come from a static apiKey (server) or a tokenBrokerUrl (client-safe).

Parameters

Parameter	Type	Description
`options`	`OpenRouterOptions`	Model id plus CredentialOptions / header overrides.

Returns

LLMProvider

createOpenRouterTTS()

function createOpenRouterTTS(options): TTSProvider;

Defined in: provider-openrouter/src/audio.ts:424

OpenRouter TTS through the OpenAI-compatible /audio/speech endpoint.

Parameters

Parameter	Type	Description
`options`	`OpenRouterTTSOptions`	Model, voice, credentials, and optional speed.

Returns

TTSProvider

A TTSProvider for the classic asr_llm_tts pipeline.

extractDelta()

function extractDelta(json): string;

Defined in: provider-openrouter/src/chat.ts:110

Extract the incremental text from a streamed chunk.

Parameters

Parameter	Type
`json`	`ChatCompletion`

Returns

string

extractText()

function extractText(json): string;

Defined in: provider-openrouter/src/chat.ts:105

Extract the assistant text from a non-streamed completion.

Parameters

Parameter	Type
`json`	`ChatCompletion`

Returns

string

mapUsage()

function mapUsage(usage):
  | LLMUsage
  | undefined;

Defined in: provider-openrouter/src/chat.ts:90

Map an OpenAI-style usage object to the core LLMUsage shape.

Parameters

Parameter	Type
`usage`	`RawUsage` \| `null` \| `undefined`

Returns

| LLMUsage | undefined

pcm16ToWav()

function pcm16ToWav(pcm, sampleRate?): ArrayBuffer;

Defined in: provider-openrouter/src/audio-llm.ts:133

Wrap OpenAI’s 24 kHz mono PCM16 stream so browser audio elements can play it.

Parameters

Parameter	Type	Default value	Description
`pcm`	`Uint8Array`	`undefined`	Interleaved little-endian PCM16 bytes.
`sampleRate`	`number`	`24_000`	Sample rate in Hz (OpenAI audio chat defaults to 24_000).

Returns

ArrayBuffer

A standard WAV container buffer.