OpenAI-compatible Provider

Overview

The OpenAI-compatible provider connects core-ai to third-party endpoints that implement the Chat Completions API. It accepts known nonstandard response fields used by gateways and inference servers. It provides models through the Chat Completions API with compatibility extensions enabled. Use @core-ai/openai for OpenAI’s Responses API, strict Chat Completions, embeddings, and image generation.

Installation

npm install @core-ai/openai-compat

createOpenAICompat()

import { createOpenAICompat } from '@core-ai/openai-compat';

const provider = createOpenAICompat({
    apiKey: process.env.GATEWAY_API_KEY,
    baseURL: 'https://gateway.example.com/v1',
});

Options

string

API key sent to the compatible endpoint.

string

Base URL for the compatible Chat Completions endpoint.

OpenAI

A configured OpenAI SDK client.

boolean

Whether to extract nonstandard reasoning_content and reasoning response fields. Defaults to true.

'tool' | 'json-schema' | 'json-object'

How generateObject() and streamObject() request structured output. Defaults to tool for broad endpoint compatibility. Set this to json-schema when the endpoint supports strict JSON Schema response formats. Use json-object for endpoints that support JSON Mode without JSON Schema.

'max_tokens' | 'max_completion_tokens'

Request parameter used for maxTokens across this provider. When unset, known OpenAI models use their registered capability and unknown models use max_tokens.

Returns

OpenAICompatProvider with a single chatModel() method.

Generate text

import { generate } from '@core-ai/core-ai';
import { createOpenAICompat } from '@core-ai/openai-compat';

const provider = createOpenAICompat({
    apiKey: process.env.GATEWAY_API_KEY,
    baseURL: 'https://gateway.example.com/v1',
});

const result = await generate({
    model: provider.chatModel('qwen3-235b'),
    messages: [{ role: 'user', content: 'Explain the result.' }],
});

console.log(result.content);
console.log(result.reasoning);

Model capabilities

Each model exposes model.capabilities for unified reasoning, sampling, and tool-choice constraints:

const model = provider.chatModel('qwen3-235b');
const capabilities = model.capabilities;

Known OpenAI model IDs use the OpenAI registry. Other IDs use generic OpenAI-compatible fallback capabilities because the provider cannot infer vendor-specific behavior from an arbitrary endpoint. Treat those values as defaults and configure endpoint-specific wire behavior with structuredOutputMode, maxTokensParameter, and reasoning. The fallback includes 'image' and 'file' in modalities.input, so multimodal requests are forwarded to the endpoint rather than rejected locally. The reasoning provider option controls extraction of nonstandard response fields; it does not change model.capabilities.

System messages

Every model reports model.capabilities.messages.systemPlacement as 'anywhere', and system messages are sent exactly where they appear. The provider cannot see the endpoint’s chat template, and some self-hosted chat templates reject a system message that is not first. Keep all system messages at the start of the conversation for those endpoints.

Strict tool schemas

Tools with strict: true are forwarded per tool with strict: true and a normalized schema; other tools are sent unchanged. Endpoints that do not implement OpenAI strict function tools reject or ignore the field, so opt tools in only when the target endpoint supports the OpenAI contract. See Strict tool schemas for the schema contract and error reasons.

Compatibility behavior

The provider follows the standard Chat Completions request and response shapes, then recognizes these additional reasoning output fields:

reasoning_content, used by DeepSeek, Qwen, GLM, vLLM, and SGLang
reasoning, used by OpenRouter

Non-streaming values become reasoning parts and populate result.reasoning. Streaming values emit reasoning-start, reasoning-delta, and reasoning-end events. Structured output uses a forced function tool by default because support for response_format.json_schema varies between compatible endpoints. Endpoints that implement strict JSON Schema output can opt in:

const provider = createOpenAICompat({
    apiKey: process.env.GATEWAY_API_KEY,
    baseURL: 'https://gateway.example.com/v1',
    structuredOutputMode: 'json-schema',
});

Endpoints that implement JSON Mode can use json-object. The provider adds the schema to the system message as is, optional keys included, and sends response_format: { type: 'json_object' }:

const provider = createOpenAICompat({
    apiKey: process.env.GATEWAY_API_KEY,
    baseURL: 'https://gateway.example.com/v1',
    structuredOutputMode: 'json-object',
});

Strict OpenAI Chat Completions does not expose reasoning text. Use createOpenAI().chat.chatModel() when you do not want compatibility extensions.

Provider-specific options

Pass Chat Completions options through providerOptions['openai-compat']:

const result = await generate({
    model: provider.chatModel('qwen3-235b'),
    messages: [{ role: 'user', content: 'Hello' }],
    maxTokens: 1024,
    providerOptions: {
        'openai-compat': {
            stopSequences: ['\n\n'],
            frequencyPenalty: 0.5,
            presencePenalty: 0.3,
            seed: 42,
        },
    },
});

Supported fields are store, serviceTier, parallelToolCalls, user, stopSequences, frequencyPenalty, presencePenalty, and seed. Known OpenAI models select their required token-limit parameter automatically. Unknown model IDs use max_tokens, which has the broadest compatibility. Set maxTokensParameter on createOpenAICompat() when every model exposed by the endpoint requires a different parameter.

Core

Providers

OpenAI-compatible Provider

Overview

Installation

createOpenAICompat()

Options

Returns

Generate text

Model capabilities

System messages

Strict tool schemas

Compatibility behavior

Provider-specific options

​Overview

​Installation

​createOpenAICompat()

​Options

​Returns

​Generate text

​Model capabilities

​System messages

​Strict tool schemas

​Compatibility behavior

​Provider-specific options

Overview

Installation

createOpenAICompat()

Options

Returns

Generate text

Model capabilities

System messages

Strict tool schemas

Compatibility behavior

Provider-specific options