@openrouter/ai-sdk-provider 2.0.2 → 2.1.0

package/README.md

@@ -307,6 +307,34 @@ for await (const partialComponent of result.partialObjectStream) {
 
 ## Use Cases
 
+### Response Healing for Structured Outputs
+
+The provider supports the [Response Healing plugin](https://openrouter.ai/docs/guides/features/plugins/response-healing), which automatically validates and repairs malformed JSON responses from AI models. This is particularly useful when using `generateObject` or structured outputs, as it can fix common issues like missing brackets, trailing commas, markdown wrappers, and mixed text.
+
+```typescript
+import { createOpenRouter } from '@openrouter/ai-sdk-provider';
+import { generateObject } from 'ai';
+import { z } from 'zod';
+
+const openrouter = createOpenRouter({ apiKey: 'your-api-key' });
+const model = openrouter('openai/gpt-4o', {
+  plugins: [{ id: 'response-healing' }],
+});
+
+const { object } = await generateObject({
+  model,
+  schema: z.object({
+    name: z.string(),
+    age: z.number(),
+  }),
+  prompt: 'Generate a person with name and age.',
+});
+
+console.log(object); // { name: "John", age: 30 }
+```
+
+Note that Response Healing only works with non-streaming requests. When the model returns imperfect JSON formatting, the plugin attempts to repair the response so you receive valid, parseable JSON.
+
 ### Debugging API Requests
 
 The provider supports a debug mode that echoes back the request body sent to the upstream provider. This is useful for troubleshooting and understanding how your requests are being processed. Note that debug mode only works with streaming requests.

package/dist/index.d.mts

@@ -1,9 +1,52 @@
 import * as _ai_sdk_provider from '@ai-sdk/provider';
-import { LanguageModelV3, LanguageModelV3CallOptions, LanguageModelV3Content, LanguageModelV3FinishReason, LanguageModelV3Usage, SharedV3Warning, LanguageModelV3ResponseMetadata, SharedV3Headers, LanguageModelV3StreamPart, EmbeddingModelV3, SharedV3ProviderMetadata, ProviderV3 } 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 * as models from '@openrouter/sdk/models';
 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';
+/**
+ * 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 = {
     /**
@@ -46,18 +89,29 @@ type OpenRouterChatSettings = {
      * Plugin configurations for enabling various capabilities
      */
     plugins?: Array<{
-        id: models.IdWeb;
+        id: IdWeb;
         max_results?: number;
         search_prompt?: string;
-        engine?: models.Engine;
+        engine?: Engine;
     } | {
-        id: models.IdFileParser;
+        id: IdFileParser;
         max_files?: number;
         pdf?: {
-            engine?: models.PdfEngine;
+            engine?: PdfEngine;
         };
     } | {
-        id: models.IdModeration;
+        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;
     }>;
     /**
      * Built-in web search options for models that support native web search
@@ -78,7 +132,7 @@ type OpenRouterChatSettings = {
          * - undefined: Native if supported, otherwise Exa
          * @see https://openrouter.ai/docs/features/web-search
          */
-        engine?: models.Engine;
+        engine?: Engine;
     };
     /**
      * Debug options for troubleshooting API requests.
@@ -112,7 +166,7 @@ type OpenRouterChatSettings = {
         /**
          * Control whether to use providers that may store data
          */
-        data_collection?: models.DataCollection;
+        data_collection?: DataCollection;
         /**
          * List of provider slugs to allow for this request
          */
@@ -124,11 +178,11 @@ type OpenRouterChatSettings = {
         /**
          * List of quantization levels to filter by (e.g. ["int4", "int8"])
          */
-        quantizations?: Array<models.Quantization>;
+        quantizations?: Array<Quantization>;
         /**
          * Sort providers by price, throughput, or latency
          */
-        sort?: models.ProviderSort;
+        sort?: ProviderSort;
         /**
          * Maximum pricing you want to pay for this request
          */
@@ -199,6 +253,52 @@ type OpenRouterEmbeddingSettings = {
     };
 } & 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[];
     /**
@@ -445,6 +545,37 @@ declare class OpenRouterEmbeddingModel implements EmbeddingModelV3 {
     }>;
 }
 
+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;
@@ -467,6 +598,10 @@ interface OpenRouterProvider extends ProviderV3 {
   @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 {
     /**
@@ -551,4 +686,4 @@ declare class OpenRouter {
     embedding(modelId: OpenRouterEmbeddingModelId, settings?: OpenRouterEmbeddingSettings): OpenRouterEmbeddingModel;
 }
 
-export { OpenRouter, type OpenRouterChatSettings, type OpenRouterCompletionSettings, type OpenRouterEmbeddingModelId, type OpenRouterEmbeddingSettings, type OpenRouterProvider, type OpenRouterProviderOptions, type OpenRouterProviderSettings, type OpenRouterSharedSettings, type OpenRouterUsageAccounting, createOpenRouter, openrouter };
+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 };

package/dist/index.d.ts

@@ -1,9 +1,52 @@
 import * as _ai_sdk_provider from '@ai-sdk/provider';
-import { LanguageModelV3, LanguageModelV3CallOptions, LanguageModelV3Content, LanguageModelV3FinishReason, LanguageModelV3Usage, SharedV3Warning, LanguageModelV3ResponseMetadata, SharedV3Headers, LanguageModelV3StreamPart, EmbeddingModelV3, SharedV3ProviderMetadata, ProviderV3 } 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 * as models from '@openrouter/sdk/models';
 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';
+/**
+ * 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 = {
     /**
@@ -46,18 +89,29 @@ type OpenRouterChatSettings = {
      * Plugin configurations for enabling various capabilities
      */
     plugins?: Array<{
-        id: models.IdWeb;
+        id: IdWeb;
         max_results?: number;
         search_prompt?: string;
-        engine?: models.Engine;
+        engine?: Engine;
     } | {
-        id: models.IdFileParser;
+        id: IdFileParser;
         max_files?: number;
         pdf?: {
-            engine?: models.PdfEngine;
+            engine?: PdfEngine;
         };
     } | {
-        id: models.IdModeration;
+        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;
     }>;
     /**
      * Built-in web search options for models that support native web search
@@ -78,7 +132,7 @@ type OpenRouterChatSettings = {
          * - undefined: Native if supported, otherwise Exa
          * @see https://openrouter.ai/docs/features/web-search
          */
-        engine?: models.Engine;
+        engine?: Engine;
     };
     /**
      * Debug options for troubleshooting API requests.
@@ -112,7 +166,7 @@ type OpenRouterChatSettings = {
         /**
          * Control whether to use providers that may store data
          */
-        data_collection?: models.DataCollection;
+        data_collection?: DataCollection;
         /**
          * List of provider slugs to allow for this request
          */
@@ -124,11 +178,11 @@ type OpenRouterChatSettings = {
         /**
          * List of quantization levels to filter by (e.g. ["int4", "int8"])
          */
-        quantizations?: Array<models.Quantization>;
+        quantizations?: Array<Quantization>;
         /**
          * Sort providers by price, throughput, or latency
          */
-        sort?: models.ProviderSort;
+        sort?: ProviderSort;
         /**
          * Maximum pricing you want to pay for this request
          */
@@ -199,6 +253,52 @@ type OpenRouterEmbeddingSettings = {
     };
 } & 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[];
     /**
@@ -445,6 +545,37 @@ declare class OpenRouterEmbeddingModel implements EmbeddingModelV3 {
     }>;
 }
 
+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;
@@ -467,6 +598,10 @@ interface OpenRouterProvider extends ProviderV3 {
   @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 {
     /**
@@ -551,4 +686,4 @@ declare class OpenRouter {
     embedding(modelId: OpenRouterEmbeddingModelId, settings?: OpenRouterEmbeddingSettings): OpenRouterEmbeddingModel;
 }
 
-export { OpenRouter, type OpenRouterChatSettings, type OpenRouterCompletionSettings, type OpenRouterEmbeddingModelId, type OpenRouterEmbeddingSettings, type OpenRouterProvider, type OpenRouterProviderOptions, type OpenRouterProviderSettings, type OpenRouterSharedSettings, type OpenRouterUsageAccounting, createOpenRouter, openrouter };
+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 };