@openrouter/ai-sdk-provider
Version:
The [OpenRouter](https://openrouter.ai/) provider for the [Vercel AI SDK](https://sdk.vercel.ai/docs) gives access to over 300 large language models on the OpenRouter chat and completion APIs.
707 lines (683 loc) • 25.8 kB
TypeScript
import * as _ai_sdk_provider from '@ai-sdk/provider';
import { LanguageModelV3, LanguageModelV3CallOptions, LanguageModelV3Content, LanguageModelV3FinishReason, LanguageModelV3Usage, SharedV3Warning, LanguageModelV3ResponseMetadata, SharedV3Headers, LanguageModelV3StreamPart, EmbeddingModelV3, SharedV3ProviderMetadata, ImageModelV3, ImageModelV3CallOptions, ImageModelV3ProviderMetadata, ImageModelV3Usage, ProviderV3 } from '@ai-sdk/provider';
export { LanguageModelV3, LanguageModelV3Prompt } from '@ai-sdk/provider';
import { z } from 'zod/v4';
/**
* Plugin identifier for web search functionality.
*/
type IdWeb = 'web';
/**
* Plugin identifier for file parsing functionality.
*/
type IdFileParser = 'file-parser';
/**
* Plugin identifier for content moderation.
*/
type IdModeration = 'moderation';
/**
* Plugin identifier for response healing.
* Automatically validates and repairs malformed JSON responses.
* @see https://openrouter.ai/docs/guides/features/plugins/response-healing
*/
type IdResponseHealing = 'response-healing';
/**
* Plugin identifier for auto-router model selection.
* Configures allowed models when using the openrouter/auto model.
* @see https://openrouter.ai/docs/guides/routing/routers/auto-router
*/
type IdAutoRouter = 'auto-router';
/**
* Search engine options for web search.
* Open enum - accepts known values or any string for forward compatibility.
*/
type Engine = 'native' | 'exa' | (string & {});
/**
* PDF processing engine options.
* Open enum - accepts known values or any string for forward compatibility.
*/
type PdfEngine = 'mistral-ocr' | 'pdf-text' | 'native' | (string & {});
/**
* Data collection preference for provider routing.
* Open enum - accepts known values or any string for forward compatibility.
*/
type DataCollection = 'deny' | 'allow' | (string & {});
/**
* Model quantization levels for provider filtering.
* Open enum - accepts known values or any string for forward compatibility.
*/
type Quantization = 'int4' | 'int8' | 'fp4' | 'fp6' | 'fp8' | 'fp16' | 'bf16' | 'fp32' | 'unknown' | (string & {});
/**
* Provider sorting strategy options.
* Open enum - accepts known values or any string for forward compatibility.
*/
type ProviderSort = 'price' | 'throughput' | 'latency' | (string & {});
type OpenRouterChatModelId = string;
type OpenRouterChatSettings = {
/**
Modify the likelihood of specified tokens appearing in the completion.
Accepts a JSON object that maps tokens (specified by their token ID in
the GPT tokenizer) to an associated bias value from -100 to 100. You
can use this tokenizer tool to convert text to token IDs. Mathematically,
the bias is added to the logits generated by the model prior to sampling.
The exact effect will vary per model, but values between -1 and 1 should
decrease or increase likelihood of selection; values like -100 or 100
should result in a ban or exclusive selection of the relevant token.
As an example, you can pass {"50256": -100} to prevent the <|endoftext|>
token from being generated.
*/
logitBias?: Record<number, number>;
/**
Return the log probabilities of the tokens. Including logprobs will increase
the response size and can slow down response times. However, it can
be useful to understand better how the model is behaving.
Setting to true will return the log probabilities of the tokens that
were generated.
Setting to a number will return the log probabilities of the top n
tokens that were generated.
*/
logprobs?: boolean | number;
/**
Whether to enable parallel function calling during tool use. Default to true.
*/
parallelToolCalls?: boolean;
/**
A unique identifier representing your end-user, which can help OpenRouter to
monitor and detect abuse. Learn more.
*/
user?: string;
/**
* Plugin configurations for enabling various capabilities
*/
plugins?: Array<{
id: IdWeb;
max_results?: number;
search_prompt?: string;
engine?: Engine;
} | {
id: IdFileParser;
max_files?: number;
pdf?: {
engine?: PdfEngine;
};
} | {
id: IdModeration;
} | {
/**
* Response healing plugin - automatically validates and repairs malformed JSON responses.
*
* **Important:** This plugin only works with non-streaming requests (e.g., `generateObject`).
* It has no effect when used with streaming methods like `streamObject` or `streamText`.
* The plugin activates when using `response_format` with `json_schema` or `json_object`.
*
* @see https://openrouter.ai/docs/guides/features/plugins/response-healing
*/
id: IdResponseHealing;
} | {
/**
* Auto-router plugin - configures allowed models when using `openrouter/auto`.
*
* Use wildcard patterns to restrict which models the auto router can select from.
* When no `allowed_models` are specified, the auto router uses all supported models.
*
* @see https://openrouter.ai/docs/guides/routing/routers/auto-router
*/
id: IdAutoRouter;
allowed_models?: string[];
}>;
/**
* Built-in web search options for models that support native web search
*/
web_search_options?: {
/**
* Maximum number of search results to include
*/
max_results?: number;
/**
* Custom search prompt to guide the search query
*/
search_prompt?: string;
/**
* Search engine to use for web search
* - "native": Use provider's built-in web search
* - "exa": Use Exa's search API
* - undefined: Native if supported, otherwise Exa
* @see https://openrouter.ai/docs/features/web-search
*/
engine?: Engine;
};
/**
* Debug options for troubleshooting API requests.
* Only works with streaming requests.
* @see https://openrouter.ai/docs/api-reference/debugging
*/
debug?: {
/**
* When true, echoes back the request body that was sent to the upstream provider.
* The debug data will be returned as the first chunk in the stream with a `debug.echo_upstream_body` field.
* Sensitive data like user IDs and base64 content will be redacted.
*/
echo_upstream_body?: boolean;
};
/**
* Provider routing preferences to control request routing behavior
*/
provider?: {
/**
* List of provider slugs to try in order (e.g. ["anthropic", "openai"])
*/
order?: string[];
/**
* Whether to allow backup providers when primary is unavailable (default: true)
*/
allow_fallbacks?: boolean;
/**
* Only use providers that support all parameters in your request (default: false)
*/
require_parameters?: boolean;
/**
* Control whether to use providers that may store data
*/
data_collection?: DataCollection;
/**
* List of provider slugs to allow for this request
*/
only?: string[];
/**
* List of provider slugs to skip for this request
*/
ignore?: string[];
/**
* List of quantization levels to filter by (e.g. ["int4", "int8"])
*/
quantizations?: Array<Quantization>;
/**
* Sort providers by price, throughput, or latency
*/
sort?: ProviderSort;
/**
* Maximum pricing you want to pay for this request
*/
max_price?: {
prompt?: number | string;
completion?: number | string;
image?: number | string;
audio?: number | string;
request?: number | string;
};
/**
* Whether to restrict routing to only ZDR (Zero Data Retention) endpoints.
* When true, only endpoints that do not retain prompts will be used.
*/
zdr?: boolean;
};
} & OpenRouterSharedSettings;
type OpenRouterEmbeddingModelId = string;
type OpenRouterEmbeddingSettings = {
/**
* A unique identifier representing your end-user, which can help OpenRouter to
* monitor and detect abuse.
*/
user?: string;
/**
* Provider routing preferences to control request routing behavior
*/
provider?: {
/**
* List of provider slugs to try in order (e.g. ["openai", "voyageai"])
*/
order?: string[];
/**
* Whether to allow backup providers when primary is unavailable (default: true)
*/
allow_fallbacks?: boolean;
/**
* Only use providers that support all parameters in your request (default: false)
*/
require_parameters?: boolean;
/**
* Control whether to use providers that may store data
*/
data_collection?: 'allow' | 'deny';
/**
* List of provider slugs to allow for this request
*/
only?: string[];
/**
* List of provider slugs to skip for this request
*/
ignore?: string[];
/**
* Sort providers by price, throughput, or latency
*/
sort?: 'price' | 'throughput' | 'latency';
/**
* Maximum pricing you want to pay for this request
*/
max_price?: {
prompt?: number | string;
completion?: number | string;
image?: number | string;
audio?: number | string;
request?: number | string;
};
};
} & OpenRouterSharedSettings;
type OpenRouterImageModelId = string;
type OpenRouterImageSettings = {
/**
* Provider routing preferences to control request routing behavior
*/
provider?: {
/**
* List of provider slugs to try in order (e.g. ["google", "black-forest-labs"])
*/
order?: string[];
/**
* Whether to allow backup providers when primary is unavailable (default: true)
*/
allow_fallbacks?: boolean;
/**
* Only use providers that support all parameters in your request (default: false)
*/
require_parameters?: boolean;
/**
* Control whether to use providers that may store data
*/
data_collection?: 'allow' | 'deny';
/**
* List of provider slugs to allow for this request
*/
only?: string[];
/**
* List of provider slugs to skip for this request
*/
ignore?: string[];
/**
* Sort providers by price, throughput, or latency
*/
sort?: 'price' | 'throughput' | 'latency';
/**
* Maximum pricing you want to pay for this request
*/
max_price?: {
prompt?: number | string;
completion?: number | string;
image?: number | string;
request?: number | string;
};
};
} & OpenRouterSharedSettings;
type OpenRouterProviderOptions = {
models?: string[];
/**
* https://openrouter.ai/docs/use-cases/reasoning-tokens
* One of `max_tokens` or `effort` is required.
* If `exclude` is true, reasoning will be removed from the response. Default is false.
*/
reasoning?: {
enabled?: boolean;
exclude?: boolean;
} & ({
max_tokens: number;
} | {
effort: 'xhigh' | 'high' | 'medium' | 'low' | 'minimal' | 'none';
});
/**
* A unique identifier representing your end-user, which can
* help OpenRouter to monitor and detect abuse.
*/
user?: string;
};
type OpenRouterSharedSettings = OpenRouterProviderOptions & {
/**
* @deprecated use `reasoning` instead
*/
includeReasoning?: boolean;
extraBody?: Record<string, unknown>;
/**
* Enable usage accounting to get detailed token usage information.
* https://openrouter.ai/docs/use-cases/usage-accounting
*/
usage?: {
/**
* When true, includes token usage information in the response.
*/
include: boolean;
};
};
/**
* Usage accounting response
* @see https://openrouter.ai/docs/use-cases/usage-accounting
*/
type OpenRouterUsageAccounting = {
promptTokens: number;
promptTokensDetails?: {
cachedTokens: number;
};
completionTokens: number;
completionTokensDetails?: {
reasoningTokens: number;
};
totalTokens: number;
cost?: number;
costDetails?: {
upstreamInferenceCost: number;
};
};
type OpenRouterCompletionModelId = string;
type OpenRouterCompletionSettings = {
/**
Modify the likelihood of specified tokens appearing in the completion.
Accepts a JSON object that maps tokens (specified by their token ID in
the GPT tokenizer) to an associated bias value from -100 to 100. You
can use this tokenizer tool to convert text to token IDs. Mathematically,
the bias is added to the logits generated by the model prior to sampling.
The exact effect will vary per model, but values between -1 and 1 should
decrease or increase likelihood of selection; values like -100 or 100
should result in a ban or exclusive selection of the relevant token.
As an example, you can pass {"50256": -100} to prevent the <|endoftext|>
token from being generated.
*/
logitBias?: Record<number, number>;
/**
Return the log probabilities of the tokens. Including logprobs will increase
the response size and can slow down response times. However, it can
be useful to better understand how the model is behaving.
Setting to true will return the log probabilities of the tokens that
were generated.
Setting to a number will return the log probabilities of the top n
tokens that were generated.
*/
logprobs?: boolean | number;
/**
The suffix that comes after a completion of inserted text.
*/
suffix?: string;
} & OpenRouterSharedSettings;
declare enum ReasoningFormat {
Unknown = "unknown",
OpenAIResponsesV1 = "openai-responses-v1",
XAIResponsesV1 = "xai-responses-v1",
AnthropicClaudeV1 = "anthropic-claude-v1",
GoogleGeminiV1 = "google-gemini-v1"
}
declare enum ReasoningDetailType {
Summary = "reasoning.summary",
Encrypted = "reasoning.encrypted",
Text = "reasoning.text"
}
declare const ReasoningDetailUnionSchema: z.ZodUnion<readonly [z.ZodObject<{
type: z.ZodLiteral<ReasoningDetailType.Summary>;
summary: z.ZodString;
id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
format: z.ZodOptional<z.ZodNullable<z.ZodEnum<typeof ReasoningFormat>>>;
index: z.ZodOptional<z.ZodNumber>;
}, z.core.$strip>, z.ZodObject<{
type: z.ZodLiteral<ReasoningDetailType.Encrypted>;
data: z.ZodString;
id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
format: z.ZodOptional<z.ZodNullable<z.ZodEnum<typeof ReasoningFormat>>>;
index: z.ZodOptional<z.ZodNumber>;
}, z.core.$strip>, z.ZodObject<{
type: z.ZodLiteral<ReasoningDetailType.Text>;
text: z.ZodOptional<z.ZodNullable<z.ZodString>>;
signature: z.ZodOptional<z.ZodNullable<z.ZodString>>;
id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
format: z.ZodOptional<z.ZodNullable<z.ZodEnum<typeof ReasoningFormat>>>;
index: z.ZodOptional<z.ZodNumber>;
}, z.core.$strip>]>;
type ReasoningDetailUnion = z.infer<typeof ReasoningDetailUnionSchema>;
type OpenRouterChatConfig = {
provider: string;
compatibility: 'strict' | 'compatible';
headers: () => Record<string, string | undefined>;
url: (options: {
modelId: string;
path: string;
}) => string;
fetch?: typeof fetch;
extraBody?: Record<string, unknown>;
};
declare class OpenRouterChatLanguageModel implements LanguageModelV3 {
readonly specificationVersion: "v3";
readonly provider = "openrouter";
readonly defaultObjectGenerationMode: "tool";
readonly modelId: OpenRouterChatModelId;
readonly supportsImageUrls = true;
readonly supportedUrls: Record<string, RegExp[]>;
readonly settings: OpenRouterChatSettings;
private readonly config;
constructor(modelId: OpenRouterChatModelId, settings: OpenRouterChatSettings, config: OpenRouterChatConfig);
private getArgs;
doGenerate(options: LanguageModelV3CallOptions): Promise<{
content: Array<LanguageModelV3Content>;
finishReason: LanguageModelV3FinishReason;
usage: LanguageModelV3Usage;
warnings: Array<SharedV3Warning>;
providerMetadata?: {
openrouter: {
provider: string;
reasoning_details?: ReasoningDetailUnion[];
usage: OpenRouterUsageAccounting;
};
};
request?: {
body?: unknown;
};
response?: LanguageModelV3ResponseMetadata & {
headers?: SharedV3Headers;
body?: unknown;
};
}>;
doStream(options: LanguageModelV3CallOptions): Promise<{
stream: ReadableStream<LanguageModelV3StreamPart>;
warnings: Array<SharedV3Warning>;
request?: {
body?: unknown;
};
response?: LanguageModelV3ResponseMetadata & {
headers?: SharedV3Headers;
body?: unknown;
};
}>;
}
type OpenRouterCompletionConfig = {
provider: string;
compatibility: 'strict' | 'compatible';
headers: () => Record<string, string | undefined>;
url: (options: {
modelId: string;
path: string;
}) => string;
fetch?: typeof fetch;
extraBody?: Record<string, unknown>;
};
declare class OpenRouterCompletionLanguageModel implements LanguageModelV3 {
readonly specificationVersion: "v3";
readonly provider = "openrouter";
readonly modelId: OpenRouterCompletionModelId;
readonly supportsImageUrls = true;
readonly supportedUrls: Record<string, RegExp[]>;
readonly defaultObjectGenerationMode: undefined;
readonly settings: OpenRouterCompletionSettings;
private readonly config;
constructor(modelId: OpenRouterCompletionModelId, settings: OpenRouterCompletionSettings, config: OpenRouterCompletionConfig);
private getArgs;
doGenerate(options: LanguageModelV3CallOptions): Promise<Awaited<ReturnType<LanguageModelV3['doGenerate']>>>;
doStream(options: LanguageModelV3CallOptions): Promise<Awaited<ReturnType<LanguageModelV3['doStream']>>>;
}
type OpenRouterEmbeddingConfig = {
provider: string;
headers: () => Record<string, string | undefined>;
url: (options: {
modelId: string;
path: string;
}) => string;
fetch?: typeof fetch;
extraBody?: Record<string, unknown>;
};
declare class OpenRouterEmbeddingModel implements EmbeddingModelV3 {
readonly specificationVersion: "v3";
readonly provider = "openrouter";
readonly modelId: OpenRouterEmbeddingModelId;
readonly settings: OpenRouterEmbeddingSettings;
readonly maxEmbeddingsPerCall: undefined;
readonly supportsParallelCalls = true;
private readonly config;
constructor(modelId: OpenRouterEmbeddingModelId, settings: OpenRouterEmbeddingSettings, config: OpenRouterEmbeddingConfig);
doEmbed(options: {
values: Array<string>;
abortSignal?: AbortSignal;
headers?: Record<string, string | undefined>;
}): Promise<{
embeddings: Array<Array<number>>;
usage?: {
tokens: number;
};
providerMetadata?: SharedV3ProviderMetadata;
response?: {
headers?: SharedV3Headers;
body?: unknown;
};
warnings: Array<_ai_sdk_provider.SharedV3Warning>;
}>;
}
type OpenRouterImageConfig = {
provider: string;
headers: () => Record<string, string | undefined>;
url: (options: {
modelId: string;
path: string;
}) => string;
fetch?: typeof fetch;
extraBody?: Record<string, unknown>;
};
declare class OpenRouterImageModel implements ImageModelV3 {
readonly specificationVersion: "v3";
readonly provider = "openrouter";
readonly modelId: OpenRouterImageModelId;
readonly settings: OpenRouterImageSettings;
readonly maxImagesPerCall = 1;
private readonly config;
constructor(modelId: OpenRouterImageModelId, settings: OpenRouterImageSettings, config: OpenRouterImageConfig);
doGenerate(options: ImageModelV3CallOptions): Promise<{
images: Array<string>;
warnings: Array<SharedV3Warning>;
providerMetadata?: ImageModelV3ProviderMetadata;
response: {
timestamp: Date;
modelId: string;
headers: Record<string, string> | undefined;
};
usage?: ImageModelV3Usage;
}>;
}
interface OpenRouterProvider extends ProviderV3 {
(modelId: OpenRouterChatModelId, settings?: OpenRouterCompletionSettings): OpenRouterCompletionLanguageModel;
(modelId: OpenRouterChatModelId, settings?: OpenRouterChatSettings): OpenRouterChatLanguageModel;
languageModel(modelId: OpenRouterChatModelId, settings?: OpenRouterCompletionSettings): OpenRouterCompletionLanguageModel;
languageModel(modelId: OpenRouterChatModelId, settings?: OpenRouterChatSettings): OpenRouterChatLanguageModel;
/**
Creates an OpenRouter chat model for text generation.
*/
chat(modelId: OpenRouterChatModelId, settings?: OpenRouterChatSettings): OpenRouterChatLanguageModel;
/**
Creates an OpenRouter completion model for text generation.
*/
completion(modelId: OpenRouterCompletionModelId, settings?: OpenRouterCompletionSettings): OpenRouterCompletionLanguageModel;
/**
Creates an OpenRouter text embedding model. (AI SDK v5)
*/
textEmbeddingModel(modelId: OpenRouterEmbeddingModelId, settings?: OpenRouterEmbeddingSettings): OpenRouterEmbeddingModel;
/**
Creates an OpenRouter text embedding model. (AI SDK v4 - deprecated, use textEmbeddingModel instead)
@deprecated Use textEmbeddingModel instead
*/
embedding(modelId: OpenRouterEmbeddingModelId, settings?: OpenRouterEmbeddingSettings): OpenRouterEmbeddingModel;
/**
Creates an OpenRouter image model for image generation.
*/
imageModel(modelId: OpenRouterImageModelId, settings?: OpenRouterImageSettings): OpenRouterImageModel;
}
interface OpenRouterProviderSettings {
/**
Base URL for the OpenRouter API calls.
*/
baseURL?: string;
/**
@deprecated Use `baseURL` instead.
*/
baseUrl?: string;
/**
API key for authenticating requests.
*/
apiKey?: string;
/**
Custom headers to include in the requests.
*/
headers?: Record<string, string>;
/**
OpenRouter compatibility mode. Should be set to `strict` when using the OpenRouter API,
and `compatible` when using 3rd party providers. In `compatible` mode, newer
information such as streamOptions are not being sent. Defaults to 'compatible'.
*/
compatibility?: 'strict' | 'compatible';
/**
Custom fetch implementation. You can use it as a middleware to intercept requests,
or to provide a custom fetch implementation for e.g. testing.
*/
fetch?: typeof fetch;
/**
A JSON object to send as the request body to access OpenRouter features & upstream provider features.
*/
extraBody?: Record<string, unknown>;
/**
* Record of provider slugs to API keys for injecting into provider routing.
* Maps provider slugs (e.g. "anthropic", "openai") to their respective API keys.
*/
api_keys?: Record<string, string>;
}
/**
Create an OpenRouter provider instance.
*/
declare function createOpenRouter(options?: OpenRouterProviderSettings): OpenRouterProvider;
/**
Default OpenRouter provider instance. It uses 'strict' compatibility mode.
*/
declare const openrouter: OpenRouterProvider;
/**
@deprecated Use `createOpenRouter` instead.
*/
declare class OpenRouter {
/**
Use a different URL prefix for API calls, e.g. to use proxy servers.
The default prefix is `https://openrouter.ai/api/v1`.
*/
readonly baseURL: string;
/**
API key that is being sent using the `Authorization` header.
It defaults to the `OPENROUTER_API_KEY` environment variable.
*/
readonly apiKey?: string;
/**
Custom headers to include in the requests.
*/
readonly headers?: Record<string, string>;
/**
* Record of provider slugs to API keys for injecting into provider routing.
*/
readonly api_keys?: Record<string, string>;
/**
* Creates a new OpenRouter provider instance.
*/
constructor(options?: OpenRouterProviderSettings);
private get baseConfig();
chat(modelId: OpenRouterChatModelId, settings?: OpenRouterChatSettings): OpenRouterChatLanguageModel;
completion(modelId: OpenRouterCompletionModelId, settings?: OpenRouterCompletionSettings): OpenRouterCompletionLanguageModel;
textEmbeddingModel(modelId: OpenRouterEmbeddingModelId, settings?: OpenRouterEmbeddingSettings): OpenRouterEmbeddingModel;
/**
* @deprecated Use textEmbeddingModel instead
*/
embedding(modelId: OpenRouterEmbeddingModelId, settings?: OpenRouterEmbeddingSettings): OpenRouterEmbeddingModel;
}
export { OpenRouter, type OpenRouterChatSettings, type OpenRouterCompletionSettings, type OpenRouterEmbeddingModelId, type OpenRouterEmbeddingSettings, type OpenRouterImageModelId, type OpenRouterImageSettings, type OpenRouterProvider, type OpenRouterProviderOptions, type OpenRouterProviderSettings, type OpenRouterSharedSettings, type OpenRouterUsageAccounting, createOpenRouter, openrouter };