@ai-sdk/openai-compatible 2.0.15 → 2.0.17

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

@@ -0,0 +1,205 @@
+import {
+  ImageModelV3,
+  ImageModelV3File,
+  SharedV3ProviderOptions,
+  SharedV3Warning,
+} from '@ai-sdk/provider';
+import {
+  combineHeaders,
+  convertBase64ToUint8Array,
+  convertToFormData,
+  createJsonErrorResponseHandler,
+  createJsonResponseHandler,
+  downloadBlob,
+  FetchFunction,
+  postFormDataToApi,
+  postJsonToApi,
+} from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+import {
+  defaultOpenAICompatibleErrorStructure,
+  ProviderErrorStructure,
+} from '../openai-compatible-error';
+import { OpenAICompatibleImageModelId } from './openai-compatible-image-settings';
+
+export type OpenAICompatibleImageModelConfig = {
+  provider: string;
+  headers: () => Record<string, string | undefined>;
+  url: (options: { modelId: string; path: string }) => string;
+  fetch?: FetchFunction;
+  errorStructure?: ProviderErrorStructure<any>;
+  _internal?: {
+    currentDate?: () => Date;
+  };
+};
+
+export class OpenAICompatibleImageModel implements ImageModelV3 {
+  readonly specificationVersion = 'v3';
+  readonly maxImagesPerCall = 10;
+
+  get provider(): string {
+    return this.config.provider;
+  }
+
+  /**
+   * The provider options key used to extract provider-specific options.
+   */
+  private get providerOptionsKey(): string {
+    return this.config.provider.split('.')[0].trim();
+  }
+
+  constructor(
+    readonly modelId: OpenAICompatibleImageModelId,
+    private readonly config: OpenAICompatibleImageModelConfig,
+  ) {}
+
+  // TODO: deprecate non-camelCase keys and remove in future major version
+  private getArgs(
+    providerOptions: SharedV3ProviderOptions,
+  ): Record<string, unknown> {
+    return {
+      ...providerOptions[this.providerOptionsKey],
+      ...providerOptions[toCamelCase(this.providerOptionsKey)],
+    };
+  }
+
+  async doGenerate({
+    prompt,
+    n,
+    size,
+    aspectRatio,
+    seed,
+    providerOptions,
+    headers,
+    abortSignal,
+    files,
+    mask,
+  }: Parameters<ImageModelV3['doGenerate']>[0]): Promise<
+    Awaited<ReturnType<ImageModelV3['doGenerate']>>
+  > {
+    const warnings: Array<SharedV3Warning> = [];
+
+    if (aspectRatio != null) {
+      warnings.push({
+        type: 'unsupported',
+        feature: 'aspectRatio',
+        details:
+          'This model does not support aspect ratio. Use `size` instead.',
+      });
+    }
+
+    if (seed != null) {
+      warnings.push({ type: 'unsupported', feature: 'seed' });
+    }
+
+    const currentDate = this.config._internal?.currentDate?.() ?? new Date();
+
+    const args = this.getArgs(providerOptions);
+
+    // Image editing mode - use form data and /images/edits endpoint
+    if (files != null && files.length > 0) {
+      const { value: response, responseHeaders } = await postFormDataToApi({
+        url: this.config.url({
+          path: '/images/edits',
+          modelId: this.modelId,
+        }),
+        headers: combineHeaders(this.config.headers(), headers),
+        formData: convertToFormData<OpenAICompatibleFormDataInput>({
+          model: this.modelId,
+          prompt,
+          image: await Promise.all(files.map(file => fileToBlob(file))),
+          mask: mask != null ? await fileToBlob(mask) : undefined,
+          n,
+          size,
+          ...args,
+        }),
+        failedResponseHandler: createJsonErrorResponseHandler(
+          this.config.errorStructure ?? defaultOpenAICompatibleErrorStructure,
+        ),
+        successfulResponseHandler: createJsonResponseHandler(
+          openaiCompatibleImageResponseSchema,
+        ),
+        abortSignal,
+        fetch: this.config.fetch,
+      });
+
+      return {
+        images: response.data.map(item => item.b64_json),
+        warnings,
+        response: {
+          timestamp: currentDate,
+          modelId: this.modelId,
+          headers: responseHeaders,
+        },
+      };
+    }
+
+    // Standard image generation mode - use JSON and /images/generations endpoint
+    const { value: response, responseHeaders } = await postJsonToApi({
+      url: this.config.url({
+        path: '/images/generations',
+        modelId: this.modelId,
+      }),
+      headers: combineHeaders(this.config.headers(), headers),
+      body: {
+        model: this.modelId,
+        prompt,
+        n,
+        size,
+        ...args,
+        response_format: 'b64_json',
+      },
+      failedResponseHandler: createJsonErrorResponseHandler(
+        this.config.errorStructure ?? defaultOpenAICompatibleErrorStructure,
+      ),
+      successfulResponseHandler: createJsonResponseHandler(
+        openaiCompatibleImageResponseSchema,
+      ),
+      abortSignal,
+      fetch: this.config.fetch,
+    });
+
+    return {
+      images: response.data.map(item => item.b64_json),
+      warnings,
+      response: {
+        timestamp: currentDate,
+        modelId: this.modelId,
+        headers: responseHeaders,
+      },
+    };
+  }
+}
+
+// minimal version of the schema, focussed on what is needed for the implementation
+// this approach limits breakages when the API changes and increases efficiency
+const openaiCompatibleImageResponseSchema = z.object({
+  data: z.array(z.object({ b64_json: z.string() })),
+});
+
+type OpenAICompatibleFormDataInput = {
+  model: string;
+  prompt: string | undefined;
+  image: Blob | Blob[];
+  mask?: Blob;
+  n: number;
+  size: `${number}x${number}` | undefined;
+  [key: string]: unknown;
+};
+
+async function fileToBlob(file: ImageModelV3File): Promise<Blob> {
+  if (file.type === 'url') {
+    return downloadBlob(file.url);
+  }
+
+  const data =
+    file.data instanceof Uint8Array
+      ? file.data
+      : convertBase64ToUint8Array(file.data);
+
+  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/image/openai-compatible-image-settings.ts

@@ -0,0 +1 @@
+export type OpenAICompatibleImageModelId = string;

package/src/index.ts

@@ -0,0 +1,27 @@
+export { OpenAICompatibleChatLanguageModel } from './chat/openai-compatible-chat-language-model';
+export type {
+  OpenAICompatibleChatModelId,
+  OpenAICompatibleProviderOptions,
+} from './chat/openai-compatible-chat-options';
+export { OpenAICompatibleCompletionLanguageModel } from './completion/openai-compatible-completion-language-model';
+export type {
+  OpenAICompatibleCompletionModelId,
+  OpenAICompatibleCompletionProviderOptions,
+} from './completion/openai-compatible-completion-options';
+export { OpenAICompatibleEmbeddingModel } from './embedding/openai-compatible-embedding-model';
+export type {
+  OpenAICompatibleEmbeddingModelId,
+  OpenAICompatibleEmbeddingProviderOptions,
+} from './embedding/openai-compatible-embedding-options';
+export { OpenAICompatibleImageModel } from './image/openai-compatible-image-model';
+export type {
+  OpenAICompatibleErrorData,
+  ProviderErrorStructure,
+} from './openai-compatible-error';
+export type { MetadataExtractor } from './chat/openai-compatible-metadata-extractor';
+export { createOpenAICompatible } from './openai-compatible-provider';
+export type {
+  OpenAICompatibleProvider,
+  OpenAICompatibleProviderSettings,
+} from './openai-compatible-provider';
+export { VERSION } from './version';

package/src/internal/index.ts

@@ -0,0 +1,4 @@
+export { convertToOpenAICompatibleChatMessages } from '../chat/convert-to-openai-compatible-chat-messages';
+export { mapOpenAICompatibleFinishReason } from '../chat/map-openai-compatible-finish-reason';
+export { getResponseMetadata } from '../chat/get-response-metadata';
+export type { OpenAICompatibleChatConfig } from '../chat/openai-compatible-chat-language-model';

package/src/openai-compatible-error.ts

@@ -0,0 +1,30 @@
+import { z, ZodType } from 'zod/v4';
+
+export const openaiCompatibleErrorDataSchema = z.object({
+  error: z.object({
+    message: z.string(),
+
+    // The additional information below is handled loosely to support
+    // OpenAI-compatible providers that have slightly different error
+    // responses:
+    type: z.string().nullish(),
+    param: z.any().nullish(),
+    code: z.union([z.string(), z.number()]).nullish(),
+  }),
+});
+
+export type OpenAICompatibleErrorData = z.infer<
+  typeof openaiCompatibleErrorDataSchema
+>;
+
+export type ProviderErrorStructure<T> = {
+  errorSchema: ZodType<T>;
+  errorToMessage: (error: T) => string;
+  isRetryable?: (response: Response, error?: T) => boolean;
+};
+
+export const defaultOpenAICompatibleErrorStructure: ProviderErrorStructure<OpenAICompatibleErrorData> =
+  {
+    errorSchema: openaiCompatibleErrorDataSchema,
+    errorToMessage: data => data.error.message,
+  };

package/src/openai-compatible-provider.test.ts

@@ -0,0 +1,329 @@
+import { createOpenAICompatible } from './openai-compatible-provider';
+import { OpenAICompatibleChatLanguageModel } from './chat/openai-compatible-chat-language-model';
+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';
+import { vi, describe, beforeEach, it, expect } from 'vitest';
+
+// Mock version
+vi.mock('./version', () => ({
+  VERSION: '0.0.0-test',
+}));
+
+const OpenAICompatibleChatLanguageModelMock = vi.mocked(
+  OpenAICompatibleChatLanguageModel,
+);
+const OpenAICompatibleCompletionLanguageModelMock = vi.mocked(
+  OpenAICompatibleCompletionLanguageModel,
+);
+const OpenAICompatibleEmbeddingModelMock = vi.mocked(
+  OpenAICompatibleEmbeddingModel,
+);
+
+const OpenAICompatibleImageModelMock = vi.mocked(OpenAICompatibleImageModel);
+
+vi.mock('./chat/openai-compatible-chat-language-model', () => ({
+  OpenAICompatibleChatLanguageModel: vi.fn(),
+}));
+
+vi.mock('./image/openai-compatible-image-model', () => ({
+  OpenAICompatibleImageModel: vi.fn(),
+}));
+
+vi.mock('./completion/openai-compatible-completion-language-model', () => ({
+  OpenAICompatibleCompletionLanguageModel: vi.fn(),
+}));
+
+vi.mock('./embedding/openai-compatible-embedding-model', () => ({
+  OpenAICompatibleEmbeddingModel: vi.fn(),
+}));
+
+describe('OpenAICompatibleProvider', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('createOpenAICompatible', () => {
+    it('should create provider with correct configuration', () => {
+      const options = {
+        baseURL: 'https://api.example.com',
+        name: 'test-provider',
+        apiKey: 'test-api-key',
+        headers: { 'custom-header': 'value' },
+        queryParams: { 'Custom-Param': 'value' },
+      };
+
+      const provider = createOpenAICompatible(options);
+      provider('model-id');
+
+      const constructorCall =
+        OpenAICompatibleChatLanguageModelMock.mock.calls[0];
+      const config = constructorCall[1];
+      const headers = config.headers();
+
+      expect(headers).toEqual({
+        authorization: 'Bearer test-api-key',
+        'custom-header': 'value',
+        'user-agent': 'ai-sdk/openai-compatible/0.0.0-test',
+      });
+      expect(config.provider).toBe('test-provider.chat');
+      expect(config.url({ modelId: 'model-id', path: '/v1/chat' })).toBe(
+        'https://api.example.com/v1/chat?Custom-Param=value',
+      );
+    });
+
+    it('should create headers without authorization when no apiKey provided', () => {
+      const options = {
+        baseURL: 'https://api.example.com',
+        name: 'test-provider',
+        headers: { 'custom-header': 'value' },
+      };
+
+      const provider = createOpenAICompatible(options);
+      provider('model-id');
+
+      const constructorCall =
+        OpenAICompatibleChatLanguageModelMock.mock.calls[0];
+      const config = constructorCall[1];
+      const headers = config.headers();
+
+      expect(headers).toEqual({
+        'custom-header': 'value',
+        'user-agent': 'ai-sdk/openai-compatible/0.0.0-test',
+      });
+    });
+  });
+
+  describe('model creation methods', () => {
+    const defaultOptions = {
+      baseURL: 'https://api.example.com',
+      name: 'test-provider',
+      apiKey: 'test-api-key',
+      headers: { 'custom-header': 'value' },
+      queryParams: { 'Custom-Param': 'value' },
+    };
+
+    it('should create chat model with correct configuration', () => {
+      const provider = createOpenAICompatible(defaultOptions);
+
+      provider.chatModel('chat-model');
+
+      const constructorCall =
+        OpenAICompatibleChatLanguageModelMock.mock.calls[0];
+      const config = constructorCall[1];
+      const headers = config.headers();
+
+      expect(headers).toEqual({
+        authorization: 'Bearer test-api-key',
+        'custom-header': 'value',
+        'user-agent': 'ai-sdk/openai-compatible/0.0.0-test',
+      });
+      expect(config.provider).toBe('test-provider.chat');
+      expect(config.url({ modelId: 'model-id', path: '/v1/chat' })).toBe(
+        'https://api.example.com/v1/chat?Custom-Param=value',
+      );
+    });
+
+    it('should create completion model with correct configuration', () => {
+      const provider = createOpenAICompatible(defaultOptions);
+
+      provider.completionModel('completion-model');
+
+      const constructorCall =
+        OpenAICompatibleCompletionLanguageModelMock.mock.calls[0];
+      const config = constructorCall[1];
+      const headers = config.headers();
+
+      expect(headers).toEqual({
+        authorization: 'Bearer test-api-key',
+        'custom-header': 'value',
+        'user-agent': 'ai-sdk/openai-compatible/0.0.0-test',
+      });
+      expect(config.provider).toBe('test-provider.completion');
+      expect(
+        config.url({ modelId: 'completion-model', path: '/v1/completions' }),
+      ).toBe('https://api.example.com/v1/completions?Custom-Param=value');
+    });
+
+    it('should create embedding model with correct configuration', () => {
+      const provider = createOpenAICompatible(defaultOptions);
+
+      provider.embeddingModel('embedding-model');
+
+      const constructorCall = OpenAICompatibleEmbeddingModelMock.mock.calls[0];
+      const config = constructorCall[1];
+      const headers = config.headers();
+
+      expect(headers).toEqual({
+        authorization: 'Bearer test-api-key',
+        'custom-header': 'value',
+        'user-agent': 'ai-sdk/openai-compatible/0.0.0-test',
+      });
+      expect(config.provider).toBe('test-provider.embedding');
+      expect(
+        config.url({ modelId: 'embedding-model', path: '/v1/embeddings' }),
+      ).toBe('https://api.example.com/v1/embeddings?Custom-Param=value');
+    });
+
+    it('should use languageModel as default when called as function', () => {
+      const provider = createOpenAICompatible(defaultOptions);
+
+      provider('model-id');
+
+      expect(OpenAICompatibleChatLanguageModel).toHaveBeenCalledWith(
+        'model-id',
+        expect.objectContaining({
+          provider: 'test-provider.chat',
+        }),
+      );
+    });
+
+    it('should create URL without query parameters when queryParams is not specified', () => {
+      const options = {
+        baseURL: 'https://api.example.com',
+        name: 'test-provider',
+        apiKey: 'test-api-key',
+      };
+
+      const provider = createOpenAICompatible(options);
+      provider('model-id');
+
+      const constructorCall =
+        OpenAICompatibleChatLanguageModelMock.mock.calls[0];
+      const config = constructorCall[1];
+
+      expect(config.url({ modelId: 'model-id', path: '/v1/chat' })).toBe(
+        'https://api.example.com/v1/chat',
+      );
+    });
+  });
+
+  describe('includeUsage setting', () => {
+    it('should pass includeUsage: true to all model types when specified in provider settings', () => {
+      const options = {
+        baseURL: 'https://api.example.com',
+        name: 'test-provider',
+        includeUsage: true,
+      };
+      const provider = createOpenAICompatible(options);
+
+      provider.chatModel('chat-model');
+      expect(
+        OpenAICompatibleChatLanguageModelMock.mock.calls[0][1].includeUsage,
+      ).toBe(true);
+
+      provider.completionModel('completion-model');
+      expect(
+        OpenAICompatibleCompletionLanguageModelMock.mock.calls[0][1]
+          .includeUsage,
+      ).toBe(true);
+
+      provider('model-id');
+      expect(
+        OpenAICompatibleChatLanguageModelMock.mock.calls[1][1].includeUsage,
+      ).toBe(true);
+    });
+
+    it('should pass includeUsage: false to all model types when specified in provider settings', () => {
+      const options = {
+        baseURL: 'https://api.example.com',
+        name: 'test-provider',
+        includeUsage: false,
+      };
+      const provider = createOpenAICompatible(options);
+
+      provider.chatModel('chat-model');
+      expect(
+        OpenAICompatibleChatLanguageModelMock.mock.calls[0][1].includeUsage,
+      ).toBe(false);
+
+      provider.completionModel('completion-model');
+      expect(
+        OpenAICompatibleCompletionLanguageModelMock.mock.calls[0][1]
+          .includeUsage,
+      ).toBe(false);
+
+      provider('model-id');
+      expect(
+        OpenAICompatibleChatLanguageModelMock.mock.calls[1][1].includeUsage,
+      ).toBe(false);
+    });
+
+    it('should pass includeUsage: undefined to all model types when not specified in provider settings', () => {
+      const options = {
+        baseURL: 'https://api.example.com',
+        name: 'test-provider',
+      };
+      const provider = createOpenAICompatible(options);
+
+      provider.chatModel('chat-model');
+      expect(
+        OpenAICompatibleChatLanguageModelMock.mock.calls[0][1].includeUsage,
+      ).toBeUndefined();
+
+      provider.completionModel('completion-model');
+      expect(
+        OpenAICompatibleCompletionLanguageModelMock.mock.calls[0][1]
+          .includeUsage,
+      ).toBeUndefined();
+
+      provider('model-id');
+      expect(
+        OpenAICompatibleChatLanguageModelMock.mock.calls[1][1].includeUsage,
+      ).toBeUndefined();
+    });
+  });
+
+  describe('supportsStructuredOutputs setting', () => {
+    it('should pass supportsStructuredOutputs to to .chatModel() and .languageModel() only', () => {
+      const options = {
+        baseURL: 'https://api.example.com',
+        name: 'test-provider',
+        supportsStructuredOutputs: true,
+      };
+      const provider = createOpenAICompatible(options);
+
+      provider('model-id');
+      expect(
+        OpenAICompatibleChatLanguageModelMock.mock.calls[0][1]
+          .supportsStructuredOutputs,
+      ).toBe(true);
+
+      provider.chatModel('chat-model');
+      expect(
+        OpenAICompatibleChatLanguageModelMock.mock.calls[1][1]
+          .supportsStructuredOutputs,
+      ).toBe(true);
+
+      provider.languageModel('completion-model');
+      expect(
+        OpenAICompatibleChatLanguageModelMock.mock.calls[2][1]
+          .supportsStructuredOutputs,
+      ).toBe(true);
+
+      provider.completionModel('completion-model');
+      const completionModelConfigArg =
+        OpenAICompatibleCompletionLanguageModelMock.mock.calls[0][1];
+      expect(
+        // @ts-expect-error - testing
+        completionModelConfigArg.supportsStructuredOutputs,
+      ).toBe(undefined);
+
+      provider.embeddingModel('embedding-model');
+      const embeddingModelConfigArg =
+        OpenAICompatibleEmbeddingModelMock.mock.calls[0][1];
+      expect(
+        // @ts-expect-error - testing
+        embeddingModelConfigArg.supportsStructuredOutputs,
+      ).toBe(undefined);
+
+      provider.imageModel('image-model');
+      const imageModelConfigArg =
+        OpenAICompatibleImageModelMock.mock.calls[0][1];
+      expect(
+        // @ts-expect-error - testing
+        imageModelConfigArg.supportsStructuredOutputs,
+      ).toBe(undefined);
+    });
+  });
+});