openai-compatible/options

22 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Custom provider settings interface

The provider settings interface should include: apiKey (optional string for the API key), baseURL (optional string for base URL of API calls), headers (optional Record<string, string> for custom headers), queryParams (optional Record<string, string> for URL query parameters), and fetch (optional FetchFunction for custom fetch implementation and request interception).

createOpenAICompatible function parameters

The createOpenAICompatible function accepts the following parameters: name (string, required), apiKey (string, optional), baseURL (string, optional), headers (Record<string,string>, optional), queryParams (Record<string,string>, optional), fetch (custom fetch implementation, optional), includeUsage (boolean, optional, defaults to undefined/false), supportsStructuredOutputs (boolean, optional), transformRequestBody (function to transform request body, optional), and metadataExtractor (optional metadata extractor).

baseURL option for OpenAI Compatible Provider

The baseURL parameter sets the URL prefix for API calls made by the provider.

apiKey option for OpenAI Compatible Provider

The apiKey parameter is used for authenticating requests. If specified, adds an Authorization header to request headers with the value Bearer <apiKey>. This header is added before any headers potentially specified in the headers option.

headers option for OpenAI Compatible Provider

The headers parameter accepts optional custom headers as Record<string,string> to include in requests. These headers are added to request headers after any headers potentially added by use of the apiKey option.

queryParams option for OpenAI Compatible Provider

The queryParams parameter accepts optional custom URL query parameters as Record<string,string> to include in request URLs.

fetch option for OpenAI Compatible Provider

The fetch parameter allows providing a custom fetch implementation with signature (input: RequestInfo, init?: RequestInit) => Promise<Response>. It defaults to the global fetch function. It can be used as middleware to intercept requests or to provide a custom fetch implementation for testing.

includeUsage option for OpenAI Compatible Provider

The includeUsage parameter is a boolean that includes usage information in streaming responses when enabled. Usage data will be included in the response metadata for streaming requests. It defaults to undefined (false).

supportsStructuredOutputs option for OpenAI Compatible Provider

The supportsStructuredOutputs parameter is a boolean that should be set to true if the provider supports structured outputs. It is only relevant for provider(), provider.chatModel(), and provider.languageModel().

transformRequestBody option for OpenAI Compatible Provider

The transformRequestBody parameter is an optional function with signature (args: Record<string, any>) => Record<string, any> that transforms the request body before sending it to the API. This is useful for proxy providers that may require a different request format than the official OpenAI API.

metadataExtractor option for OpenAI Compatible Provider

The metadataExtractor parameter is an optional MetadataExtractor that allows capturing provider-specific metadata from API responses.

OpenAI Compatible Provider queryParams example with api-version

const provider = createOpenAICompatible({ name: 'providerName', apiKey: process.env.PROVIDER_API_KEY, baseURL: 'https://api.provider.com/v1', queryParams: { 'api-version': '1.0.0', }, });

OpenAI Compatible Provider image model options

The following common provider options are available for image models: size (string, standard dimensions via top-level size option or provider-specific values such as auto), quality (string, quality of generated image with values depending on provider and model), output_format (string, file format of generated image), and background (string, background behavior for generated image with supported values depending on provider and model). OpenAICompatibleImageModelOptions also accepts additional provider-specific options passed unchanged to the provider API.

OpenAI Compatible Provider input image formats

Input images can be provided as Buffer, ArrayBuffer, Uint8Array, base64-encoded strings, or URLs. The provider will automatically download URL-based images and convert them to the appropriate format.

OpenAI Compatible Provider chat model options

The following provider options are available for chat models via providerOptions: user (string, a unique identifier representing your end-user, which can help the provider to monitor and detect abuse), reasoningEffort (string, reasoning effort for reasoning models with exact values depending on the provider), textVerbosity (string, controls the verbosity of the generated text with exact values depending on the provider), and strictJsonSchema (boolean, whether to use strict JSON schema validation; when true, the model uses constrained decoding to guarantee schema compliance, only used when the provider supports structured outputs and a schema is provided, defaults to true).

OpenAI Compatible Provider provider-specific options in providerOptions

The OpenAI Compatible provider supports adding provider-specific options to the request body through the providerOptions field. These options are specified with a key matching the provider name in camelCase. If the provider name is 'provider-name', the options key would still be 'providerName' in camelCase. Any custom options in the providerOptions object are passed through to the provider API unchanged.

OpenAI Compatible Provider provider-specific options example

const provider = createOpenAICompatible({ name: 'providerName', apiKey: process.env.PROVIDER_API_KEY, baseURL: 'https://api.provider.com/v1', }); const { text } = await generateText({ model: provider('model-id'), prompt: 'Hello', providerOptions: { providerName: { customOption: 'magic-value' }, }, });

OpenAI Compatible Provider custom metadata extraction

The OpenAI Compatible provider supports extracting provider-specific metadata from API responses through metadata extractors. Metadata extractors receive the raw, unprocessed response data from the provider, providing complete flexibility to extract any custom fields or experimental features. This is useful when working with providers that include non-standard response fields, experimenting with beta or preview features, capturing provider-specific metrics or debugging information, or supporting rapid provider API evolution.

OpenAI Compatible Provider MetadataExtractor interface

A MetadataExtractor consists of two main components: extractMetadata function that processes complete, non-streaming responses and receives { parsedBody } to access the complete raw response, and createStreamExtractor function that returns an object with processChunk(parsedChunk) method to process each chunk's raw data and buildMetadata() method to build final metadata from accumulated data.

OpenAI Compatible Provider custom metadata extraction example

import { MetadataExtractor } from '@ai-sdk/openai-compatible'; const myMetadataExtractor: MetadataExtractor = { extractMetadata: ({ parsedBody }) => { return { myProvider: { standardUsage: parsedBody.usage, experimentalFeatures: parsedBody.beta_features, customMetrics: { processingTime: parsedBody.server_timing?.total_ms, modelVersion: parsedBody.model_version, }, }, }; }, createStreamExtractor: () => { let accumulatedData = { timing: [], customFields: {}, }; return { processChunk: parsedChunk => { if (parsedChunk.server_timing) { accumulatedData.timing.push(parsedChunk.server_timing); } if (parsedChunk.custom_data) { Object.assign(accumulatedData.customFields, parsedChunk.custom_data); } }, buildMetadata: () => ({ myProvider: { streamTiming: accumulatedData.timing, customData: accumulatedData.customFields, }, }), }; }, };

OpenAI Compatible Provider metadata extractor instantiation

A metadata extractor can be provided when creating a provider instance by passing it to the metadataExtractor parameter: const provider = createOpenAICompatible({ name: 'my-provider', apiKey: process.env.PROVIDER_API_KEY, baseURL: 'https://api.provider.com/v1', metadataExtractor: myMetadataExtractor, });

OpenAI Compatible Provider extracted metadata access

Extracted metadata is included in the response under the providerMetadata field. For example: const { text, providerMetadata } = await generateText({ model: provider('model-id'), prompt: 'Hello', }); console.log(providerMetadata.myProvider.customMetric);

Give your agent this brain