@ai-sdk/openai-compatible 3.0.0-beta.4 → 3.0.0-beta.57

package/src/completion/openai-compatible-completion-language-model.ts

@@ -1,4 +1,4 @@
-import {
+import type {
   APICallError,
   LanguageModelV4,
   LanguageModelV4CallOptions,
@@ -14,30 +14,36 @@ import {
   createEventSourceResponseHandler,
   createJsonErrorResponseHandler,
   createJsonResponseHandler,
-  FetchFunction,
   parseProviderOptions,
-  ParseResult,
   postJsonToApi,
-  ResponseHandler,
+  serializeModelOptions,
+  WORKFLOW_SERIALIZE,
+  WORKFLOW_DESERIALIZE,
+  type FetchFunction,
+  type ParseResult,
+  type ResponseHandler,
 } from '@ai-sdk/provider-utils';
 import { z } from 'zod/v4';
+import {
+  toCamelCase,
+  warnIfDeprecatedProviderOptionsKey,
+} from '../utils/to-camel-case';
 import {
   defaultOpenAICompatibleErrorStructure,
-  ProviderErrorStructure,
+  type ProviderErrorStructure,
 } from '../openai-compatible-error';
 import { convertOpenAICompatibleCompletionUsage } from './convert-openai-compatible-completion-usage';
 import { convertToOpenAICompatibleCompletionPrompt } from './convert-to-openai-compatible-completion-prompt';
 import { getResponseMetadata } from './get-response-metadata';
 import { mapOpenAICompatibleFinishReason } from './map-openai-compatible-finish-reason';
 import {
-  OpenAICompatibleCompletionModelId,
   openaiCompatibleLanguageModelCompletionOptions,
-} from './openai-compatible-completion-options';
-
+  type OpenAICompatibleCompletionModelId,
+} from './openai-compatible-completion-language-model-options';
 type OpenAICompatibleCompletionConfig = {
   provider: string;
   includeUsage?: boolean;
-  headers: () => Record<string, string | undefined>;
+  headers?: () => Record<string, string | undefined>;
   url: (options: { modelId: string; path: string }) => string;
   fetch?: FetchFunction;
   errorStructure?: ProviderErrorStructure<any>;
@@ -48,9 +54,7 @@ type OpenAICompatibleCompletionConfig = {
   supportedUrls?: () => LanguageModelV4['supportedUrls'];
 };
 
-export class OpenAICompatibleCompletionLanguageModel
-  implements LanguageModelV4
-{
+export class OpenAICompatibleCompletionLanguageModel implements LanguageModelV4 {
   readonly specificationVersion = 'v4';
 
   readonly modelId: OpenAICompatibleCompletionModelId;
@@ -58,6 +62,23 @@ export class OpenAICompatibleCompletionLanguageModel
   private readonly failedResponseHandler: ResponseHandler<APICallError>;
   private readonly chunkSchema; // type inferred via constructor
 
+  static [WORKFLOW_SERIALIZE](model: OpenAICompatibleCompletionLanguageModel) {
+    return serializeModelOptions({
+      modelId: model.modelId,
+      config: model.config,
+    });
+  }
+
+  static [WORKFLOW_DESERIALIZE](options: {
+    modelId: string;
+    config: OpenAICompatibleCompletionConfig;
+  }) {
+    return new OpenAICompatibleCompletionLanguageModel(
+      options.modelId,
+      options.config,
+    );
+  }
+
   constructor(
     modelId: OpenAICompatibleCompletionModelId,
     config: OpenAICompatibleCompletionConfig,
@@ -103,13 +124,26 @@ export class OpenAICompatibleCompletionLanguageModel
   }: LanguageModelV4CallOptions) {
     const warnings: SharedV4Warning[] = [];
 
-    // Parse provider options
-    const completionOptions =
+    // Warn when the raw (non-camelCase) provider name is used
+    warnIfDeprecatedProviderOptionsKey({
+      rawName: this.providerOptionsName,
+      providerOptions,
+      warnings,
+    });
+
+    // Parse provider options (support both raw and camelCase keys)
+    const completionOptions = Object.assign(
       (await parseProviderOptions({
         provider: this.providerOptionsName,
         providerOptions,
         schema: openaiCompatibleLanguageModelCompletionOptions,
-      })) ?? {};
+      })) ?? {},
+      (await parseProviderOptions({
+        provider: toCamelCase(this.providerOptionsName),
+        providerOptions,
+        schema: openaiCompatibleLanguageModelCompletionOptions,
+      })) ?? {},
+    );
 
     if (topK != null) {
       warnings.push({ type: 'unsupported', feature: 'topK' });
@@ -155,6 +189,7 @@ export class OpenAICompatibleCompletionLanguageModel
         presence_penalty: presencePenalty,
         seed,
         ...providerOptions?.[this.providerOptionsName],
+        ...providerOptions?.[toCamelCase(this.providerOptionsName)],
 
         // prompt:
         prompt: completionPrompt,
@@ -180,7 +215,7 @@ export class OpenAICompatibleCompletionLanguageModel
         path: '/completions',
         modelId: this.modelId,
       }),
-      headers: combineHeaders(this.config.headers(), options.headers),
+      headers: combineHeaders(this.config.headers?.(), options.headers),
       body: args,
       failedResponseHandler: this.failedResponseHandler,
       successfulResponseHandler: createJsonResponseHandler(
@@ -235,7 +270,7 @@ export class OpenAICompatibleCompletionLanguageModel
         path: '/completions',
         modelId: this.modelId,
       }),
-      headers: combineHeaders(this.config.headers(), options.headers),
+      headers: combineHeaders(this.config.headers?.(), options.headers),
       body,
       failedResponseHandler: this.failedResponseHandler,
       successfulResponseHandler: createEventSourceResponseHandler(

package/src/embedding/openai-compatible-embedding-model.ts

@@ -1,25 +1,29 @@
 import {
-  EmbeddingModelV4,
-  SharedV4Warning,
   TooManyEmbeddingValuesForCallError,
+  type EmbeddingModelV4,
+  type SharedV4Warning,
 } from '@ai-sdk/provider';
 import {
   combineHeaders,
   createJsonErrorResponseHandler,
   createJsonResponseHandler,
-  FetchFunction,
   parseProviderOptions,
   postJsonToApi,
+  serializeModelOptions,
+  WORKFLOW_SERIALIZE,
+  WORKFLOW_DESERIALIZE,
+  type FetchFunction,
 } from '@ai-sdk/provider-utils';
 import { z } from 'zod/v4';
 import {
-  OpenAICompatibleEmbeddingModelId,
   openaiCompatibleEmbeddingModelOptions,
-} from './openai-compatible-embedding-options';
+  type OpenAICompatibleEmbeddingModelId,
+} from './openai-compatible-embedding-model-options';
 import {
   defaultOpenAICompatibleErrorStructure,
-  ProviderErrorStructure,
+  type ProviderErrorStructure,
 } from '../openai-compatible-error';
+import { warnIfDeprecatedProviderOptionsKey } from '../utils/to-camel-case';
 
 type OpenAICompatibleEmbeddingConfig = {
   /**
@@ -34,7 +38,7 @@ type OpenAICompatibleEmbeddingConfig = {
 
   provider: string;
   url: (options: { modelId: string; path: string }) => string;
-  headers: () => Record<string, string | undefined>;
+  headers?: () => Record<string, string | undefined>;
   fetch?: FetchFunction;
   errorStructure?: ProviderErrorStructure<any>;
 };
@@ -57,6 +61,20 @@ export class OpenAICompatibleEmbeddingModel implements EmbeddingModelV4 {
     return this.config.supportsParallelCalls ?? true;
   }
 
+  static [WORKFLOW_SERIALIZE](model: OpenAICompatibleEmbeddingModel) {
+    return serializeModelOptions({
+      modelId: model.modelId,
+      config: model.config,
+    });
+  }
+
+  static [WORKFLOW_DESERIALIZE](options: {
+    modelId: string;
+    config: OpenAICompatibleEmbeddingConfig;
+  }) {
+    return new OpenAICompatibleEmbeddingModel(options.modelId, options.config);
+  }
+
   constructor(
     modelId: OpenAICompatibleEmbeddingModelId,
     config: OpenAICompatibleEmbeddingConfig,
@@ -88,11 +106,19 @@ export class OpenAICompatibleEmbeddingModel implements EmbeddingModelV4 {
 
     if (deprecatedOptions != null) {
       warnings.push({
-        type: 'other',
-        message: `The 'openai-compatible' key in providerOptions is deprecated. Use 'openaiCompatible' instead.`,
+        type: 'deprecated',
+        setting: "providerOptions key 'openai-compatible'",
+        message: "Use 'openaiCompatible' instead.",
       });
     }
 
+    // Warn when the raw (non-camelCase) provider name is used
+    warnIfDeprecatedProviderOptionsKey({
+      rawName: this.providerOptionsName,
+      providerOptions,
+      warnings,
+    });
+
     const compatibleOptions = Object.assign(
       deprecatedOptions ?? {},
       (await parseProviderOptions({
@@ -125,7 +151,7 @@ export class OpenAICompatibleEmbeddingModel implements EmbeddingModelV4 {
         path: '/embeddings',
         modelId: this.modelId,
       }),
-      headers: combineHeaders(this.config.headers(), headers),
+      headers: combineHeaders(this.config.headers?.(), headers),
       body: {
         model: this.modelId,
         input: values,

package/src/image/openai-compatible-image-model.ts

@@ -1,9 +1,13 @@
-import {
+import type {
   ImageModelV4,
   ImageModelV4File,
   SharedV4ProviderOptions,
   SharedV4Warning,
 } from '@ai-sdk/provider';
+import {
+  toCamelCase,
+  warnIfDeprecatedProviderOptionsKey,
+} from '../utils/to-camel-case';
 import {
   combineHeaders,
   convertBase64ToUint8Array,
@@ -11,20 +15,23 @@ import {
   createJsonErrorResponseHandler,
   createJsonResponseHandler,
   downloadBlob,
-  FetchFunction,
   postFormDataToApi,
   postJsonToApi,
+  serializeModelOptions,
+  WORKFLOW_SERIALIZE,
+  WORKFLOW_DESERIALIZE,
+  type FetchFunction,
 } from '@ai-sdk/provider-utils';
 import { z } from 'zod/v4';
 import {
   defaultOpenAICompatibleErrorStructure,
-  ProviderErrorStructure,
+  type ProviderErrorStructure,
 } from '../openai-compatible-error';
-import { OpenAICompatibleImageModelId } from './openai-compatible-image-settings';
+import type { OpenAICompatibleImageModelId } from './openai-compatible-image-settings';
 
 export type OpenAICompatibleImageModelConfig = {
   provider: string;
-  headers: () => Record<string, string | undefined>;
+  headers?: () => Record<string, string | undefined>;
   url: (options: { modelId: string; path: string }) => string;
   fetch?: FetchFunction;
   errorStructure?: ProviderErrorStructure<any>;
@@ -48,15 +55,34 @@ export class OpenAICompatibleImageModel implements ImageModelV4 {
     return this.config.provider.split('.')[0].trim();
   }
 
+  static [WORKFLOW_SERIALIZE](model: OpenAICompatibleImageModel) {
+    return serializeModelOptions({
+      modelId: model.modelId,
+      config: model.config,
+    });
+  }
+
+  static [WORKFLOW_DESERIALIZE](options: {
+    modelId: string;
+    config: OpenAICompatibleImageModelConfig;
+  }) {
+    return new OpenAICompatibleImageModel(options.modelId, options.config);
+  }
+
   constructor(
     readonly modelId: OpenAICompatibleImageModelId,
     private readonly config: OpenAICompatibleImageModelConfig,
   ) {}
 
-  // TODO: deprecate non-camelCase keys and remove in future major version
   private getArgs(
     providerOptions: SharedV4ProviderOptions,
+    warnings: SharedV4Warning[],
   ): Record<string, unknown> {
+    warnIfDeprecatedProviderOptionsKey({
+      rawName: this.providerOptionsKey,
+      providerOptions,
+      warnings,
+    });
     return {
       ...providerOptions[this.providerOptionsKey],
       ...providerOptions[toCamelCase(this.providerOptionsKey)],
@@ -94,7 +120,7 @@ export class OpenAICompatibleImageModel implements ImageModelV4 {
 
     const currentDate = this.config._internal?.currentDate?.() ?? new Date();
 
-    const args = this.getArgs(providerOptions);
+    const args = this.getArgs(providerOptions, warnings);
 
     // Image editing mode - use form data and /images/edits endpoint
     if (files != null && files.length > 0) {
@@ -103,7 +129,7 @@ export class OpenAICompatibleImageModel implements ImageModelV4 {
           path: '/images/edits',
           modelId: this.modelId,
         }),
-        headers: combineHeaders(this.config.headers(), headers),
+        headers: combineHeaders(this.config.headers?.(), headers),
         formData: convertToFormData<OpenAICompatibleFormDataInput>({
           model: this.modelId,
           prompt,
@@ -140,7 +166,7 @@ export class OpenAICompatibleImageModel implements ImageModelV4 {
         path: '/images/generations',
         modelId: this.modelId,
       }),
-      headers: combineHeaders(this.config.headers(), headers),
+      headers: combineHeaders(this.config.headers?.(), headers),
       body: {
         model: this.modelId,
         prompt,
@@ -199,7 +225,3 @@ async function fileToBlob(file: ImageModelV4File): Promise<Blob> {
 
   return new Blob([data as BlobPart], { type: file.mediaType });
 }
-
-function toCamelCase(str: string): string {
-  return str.replace(/[_-]([a-z])/g, g => g[1].toUpperCase());
-}

package/src/index.ts

@@ -4,21 +4,21 @@ export type {
   OpenAICompatibleLanguageModelChatOptions,
   /** @deprecated Use `OpenAICompatibleLanguageModelChatOptions` instead. */
   OpenAICompatibleLanguageModelChatOptions as OpenAICompatibleProviderOptions,
-} from './chat/openai-compatible-chat-options';
+} from './chat/openai-compatible-chat-language-model-options';
 export { OpenAICompatibleCompletionLanguageModel } from './completion/openai-compatible-completion-language-model';
 export type {
   OpenAICompatibleCompletionModelId,
   OpenAICompatibleLanguageModelCompletionOptions,
   /** @deprecated Use `OpenAICompatibleLanguageModelCompletionOptions` instead. */
   OpenAICompatibleLanguageModelCompletionOptions as OpenAICompatibleCompletionProviderOptions,
-} from './completion/openai-compatible-completion-options';
+} from './completion/openai-compatible-completion-language-model-options';
 export { OpenAICompatibleEmbeddingModel } from './embedding/openai-compatible-embedding-model';
 export type {
   OpenAICompatibleEmbeddingModelId,
   OpenAICompatibleEmbeddingModelOptions,
   /** @deprecated Use `OpenAICompatibleEmbeddingModelOptions` instead. */
   OpenAICompatibleEmbeddingModelOptions as OpenAICompatibleEmbeddingProviderOptions,
-} from './embedding/openai-compatible-embedding-options';
+} from './embedding/openai-compatible-embedding-model-options';
 export { OpenAICompatibleImageModel } from './image/openai-compatible-image-model';
 export type {
   OpenAICompatibleErrorData,

package/src/openai-compatible-error.ts

@@ -1,5 +1,4 @@
-import { z, ZodType } from 'zod/v4';
-
+import { z, type ZodType } from 'zod/v4';
 export const openaiCompatibleErrorDataSchema = z.object({
   error: z.object({
     message: z.string(),

package/src/openai-compatible-provider.ts

@@ -1,19 +1,19 @@
-import {
+import type {
   EmbeddingModelV4,
   ImageModelV4,
   LanguageModelV4,
   ProviderV4,
 } from '@ai-sdk/provider';
 import {
-  FetchFunction,
   withoutTrailingSlash,
   withUserAgentSuffix,
+  type FetchFunction,
 } from '@ai-sdk/provider-utils';
 import {
-  OpenAICompatibleChatConfig,
   OpenAICompatibleChatLanguageModel,
+  type OpenAICompatibleChatConfig,
 } from './chat/openai-compatible-chat-language-model';
-import { MetadataExtractor } from './chat/openai-compatible-metadata-extractor';
+import type { MetadataExtractor } from './chat/openai-compatible-metadata-extractor';
 import { OpenAICompatibleCompletionLanguageModel } from './completion/openai-compatible-completion-language-model';
 import { OpenAICompatibleEmbeddingModel } from './embedding/openai-compatible-embedding-model';
 import { OpenAICompatibleImageModel } from './image/openai-compatible-image-model';
@@ -24,7 +24,7 @@ export interface OpenAICompatibleProvider<
   COMPLETION_MODEL_IDS extends string = string,
   EMBEDDING_MODEL_IDS extends string = string,
   IMAGE_MODEL_IDS extends string = string,
-> extends Omit<ProviderV4, 'imageModel'> {
+> extends ProviderV4 {
   (modelId: CHAT_MODEL_IDS): LanguageModelV4;
 
   languageModel(
@@ -104,6 +104,17 @@ export interface OpenAICompatibleProviderSettings {
    * or provider-specific metrics from both streaming and non-streaming responses.
    */
   metadataExtractor?: MetadataExtractor;
+
+  /**
+   * The supported URLs for chat models.
+   */
+  supportedUrls?: OpenAICompatibleChatConfig['supportedUrls'];
+
+  /**
+   * Optional usage converter for providers with token accounting semantics that
+   * differ from the default OpenAI-compatible shape.
+   */
+  convertUsage?: OpenAICompatibleChatConfig['convertUsage'];
 }
 
 /**
@@ -161,8 +172,10 @@ export function createOpenAICompatible<
       ...getCommonModelConfig('chat'),
       includeUsage: options.includeUsage,
       supportsStructuredOutputs: options.supportsStructuredOutputs,
+      supportedUrls: options.supportedUrls,
       transformRequestBody: options.transformRequestBody,
       metadataExtractor: options.metadataExtractor,
+      convertUsage: options.convertUsage,
     });
 
   const createCompletionModel = (modelId: COMPLETION_MODEL_IDS) =>

package/src/utils/to-camel-case.ts

@@ -0,0 +1,43 @@
+import type { SharedV4Warning } from '@ai-sdk/provider';
+
+export function toCamelCase(str: string): string {
+  return str.replace(/[_-]([a-z])/g, g => g[1].toUpperCase());
+}
+
+/**
+Resolves which key to use for providerMetadata based on what the caller
+passed in providerOptions. Returns the camelCase variant when the caller
+supplied it, otherwise falls back to the raw name.
+*/
+export function resolveProviderOptionsKey(
+  rawName: string,
+  providerOptions: Record<string, unknown> | undefined,
+): string {
+  const camelName = toCamelCase(rawName);
+  if (camelName !== rawName && providerOptions?.[camelName] != null) {
+    return camelName;
+  }
+  return rawName;
+}
+
+/**
+Pushes a deprecation warning when the user supplies providerOptions under a non-camelCase key
+*/
+export function warnIfDeprecatedProviderOptionsKey({
+  rawName,
+  providerOptions,
+  warnings,
+}: {
+  rawName: string;
+  providerOptions: Record<string, unknown> | undefined;
+  warnings: SharedV4Warning[];
+}): void {
+  const camelName = toCamelCase(rawName);
+  if (camelName !== rawName && providerOptions?.[rawName] != null) {
+    warnings.push({
+      type: 'deprecated',
+      setting: `providerOptions key '${rawName}'`,
+      message: `Use '${camelName}' instead.`,
+    });
+  }
+}