OpenAI Provider

Overview

The OpenAI provider gives you access to GPT-5 models, o-series reasoning models, embeddings, and image generation. createOpenAI().chatModel() uses the Responses API. The same provider exposes the strict Chat Completions API through openai.chat.chatModel().

Installation

npm install @core-ai/openai

createOpenAI()

Create an OpenAI provider instance using the Responses API.

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

const openai = createOpenAI({
    apiKey: process.env.OPENAI_API_KEY,
});

Options

string

Your OpenAI API key. Defaults to OPENAI_API_KEY environment variable.

string

Custom base URL for API requests. The endpoint must support the API used by the selected model factory.

OpenAI

Provide your own configured OpenAI client instance.

Returns

OpenAIProvider with chatModel(), chat.chatModel(), embeddingModel(), and imageModel().

Chat Completions

Use the nested chat provider for OpenAI’s strict Chat Completions API:

const openai = createOpenAI({
    apiKey: process.env.OPENAI_API_KEY,
});

const model = openai.chat.chatModel('gpt-5-mini');

For third-party OpenAI-compatible endpoints, use the dedicated OpenAI-compatible provider.

Provider methods

chatModel()

const model = openai.chatModel('gpt-5-mini');

This method uses the Responses API. For Chat Completions:

const model = openai.chat.chatModel('gpt-5-mini');

embeddingModel()

const embeddings = openai.embeddingModel('text-embedding-3-large');

imageModel()

const imageGen = openai.imageModel('gpt-image-1');

Supported models

Chat models

GPT-6 Series

gpt-6.1-sol - Near-Astra model for complex coding, computer use, and professional work
gpt-6-astra - Flagship model for the hardest reasoning, coding, and computer-use work
gpt-6-sol - Strong reasoning model for demanding coding and agentic workflows
gpt-6-luna - Efficient model for focused, high-volume tasks

GPT-5 Series

gpt-5.6-sol - Flagship model with max reasoning effort for complex agentic work
gpt-5.6-terra - Balanced everyday model with GPT-5.5-class performance at lower cost
gpt-5.6-luna - Fast and affordable model for high-volume tasks
gpt-5.5 - Flagship model for complex reasoning and coding
gpt-5.5-pro - Pro model for demanding reasoning tasks
gpt-5.4 - Frontier model with max reasoning effort
gpt-5.4-pro - Pro model with enhanced reasoning
gpt-5.4-mini - Efficient GPT-5.4-class model for high-volume workloads
gpt-5.4-nano - Lightweight GPT-5.4-class model for simple high-volume tasks
gpt-5.3-codex - Agentic coding model
gpt-5.2 - Flagship with reasoning control
gpt-5.2-codex - Optimized for code generation
gpt-5.2-pro - Enhanced reasoning capabilities
gpt-5.1 - Previous generation flagship
gpt-5 - Balanced performance and cost
gpt-5-pro - Pro model with high-only reasoning effort
gpt-5-mini - Fast and efficient
gpt-5-nano - Lightweight model

o-Series (Reasoning Models)

o4-mini - Compact reasoning model
o3-pro - o3 model with more compute for harder reasoning tasks
o3 - Advanced reasoning capabilities
o3-mini - Efficient reasoning model
o1 - First-generation reasoning model
o1-mini - Compact reasoning model with no effort control

Audio Models

gpt-audio-1.5
gpt-audio
gpt-audio-mini
gpt-4o-audio-preview
gpt-4o-mini-audio-preview

Any valid OpenAI chat model ID is accepted. The models above are the ones with explicit capability handling in core-ai.

Embedding models

text-embedding-3-large - 3072 dimensions, highest quality
text-embedding-3-small - 1536 dimensions, faster and cheaper
text-embedding-ada-002 - Legacy embedding model

Image models

gpt-image-2 - Image generation model
gpt-image-1 - Image generation model used throughout the docs examples

Examples

Basic chat

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

const openai = createOpenAI();

const result = await generate({
    model: openai.chatModel('gpt-5-mini'),
    messages: [
        { role: 'user', content: 'Explain quantum computing in simple terms' },
    ],
});

console.log(result.content);

Reasoning with effort control

const result = await generate({
    model: openai.chatModel('gpt-5.4'),
    messages: [
        { role: 'user', content: 'Solve this complex mathematical proof...' },
    ],
    reasoning: {
        effort: 'max',
    },
});

Embeddings

import { embed } from '@core-ai/core-ai';

const result = await embed({
    model: openai.embeddingModel('text-embedding-3-large'),
    input: 'Search query text',
});

console.log(result.embeddings[0]);

Image generation

import { generateImage } from '@core-ai/core-ai';

const result = await generateImage({
    model: openai.imageModel('gpt-image-1'),
    prompt: 'A futuristic city at sunset',
    size: '1024x1024',
});

console.log(result.images);

Custom base URL

const openai = createOpenAI({
    apiKey: 'your-api-key',
    baseURL: 'https://your-proxy.com/v1',
});

Use openai.chat.chatModel() if the proxy implements strict Chat Completions. Use @core-ai/openai-compat if it returns nonstandard compatible fields.

Model capabilities

ChatModel.capabilities describes the selected model and API. The exported getOpenAIModelCapabilities(modelId) helper returns the registry capabilities for a model ID. Each model factory then applies its API’s restrictions: the Responses factory drops audio input, and the Chat Completions factory reports tools.toolDiscovery as 'emulated'.

Strict tool schemas

Tool-capable OpenAI models report model.capabilities.tools.strictSchemas as { supported: true }. Fine-tuned ft:<base>:... models inherit the base model’s capabilities. Unrecognized model IDs resolve optimistically to supported and rely on OpenAI to reject strict tools when the model lacks support. Two restrictions apply through both the Responses and Chat Completions APIs:

Models that predate Structured Outputs — gpt-4o-2024-05-13, GPT-4 Turbo, and GPT-3.5 Turbo — report { supported: false }.
Audio models report { supported: false }.

Non-strict tools are sent to the Responses API with an explicit strict: false so the API does not normalize them into strict mode on its own. OpenAI does not guarantee schema adherence when parallel tool calls are enabled. Set providerOptions.openai.parallelToolCalls: false on requests that combine strict tools with parallel tool calls. Strict function tools are independent of the JSON Schema response formats used by generateObject() and streamObject(). See Strict tool schemas for the schema contract and error reasons.

Tool discovery

On the Responses API, GPT-5.4 and later models with tool search report tools.toolDiscovery: 'native'. gpt-5.4-nano, gpt-5.5-pro, earlier models, and unrecognized model IDs report 'emulated'. Fine-tuned models inherit the base model’s value. Chat Completions models always report 'emulated'. Natively, the discovery tool is a client-executed tool_search tool. Discovery calls and results travel as tool_search_call and tool_search_output items. Each tool_search_output loads the snapshots of its discovery result as deferred functions, exactly as stored. The request’s tools and earlier outputs stay the same when the model discovers tools, which keeps the prompt cache. When a later discovery returns a changed snapshot, the model uses the newest definition, and the cache still holds. A snapshot whose name your tools declare is left out, and a snapshot keeps strict only while the latest snapshot of its name does. So when a name’s latest snapshot changes strictness (a refresh, a caller tool taking over the name, or the strict-tool limits stripping strict), its earlier outputs re-render and the cache is rewritten from the first one. tool_search_output holds no text, so the note of an empty result follows the step’s tool results as a developer message, which keeps the step’s reasoning. Set emulateToolDiscovery: true to declare discovered tools as ordinary functions instead, for example behind a proxy that does not forward the tool search items:

const result = await generate({
    model: openai.chatModel('gpt-5.4'),
    messages,
    toolDiscovery: { description: 'Discoverable tools: get_order_status.' },
    providerOptions: {
        openai: { emulateToolDiscovery: true },
    },
});

See Tool Discovery for the agent loop and rules.

Structured output schemas

generateObject() and streamObject() send the schema as a strict JSON Schema response format, which requires an object root and closed objects with every key required. core-ai makes a key required when that keeps the schema’s meaning: when the key declares a default or also accepts null (through type: 'null', a type array that includes 'null', or an anyOf branch). Any other optional key throws a ValidationError before the request, listing the path of each such key. In Zod, use .nullable() instead of .optional(). Strict tools follow the same rule.

Reasoning support

Inspect the supported effort levels before enabling reasoning:

import { clampReasoningEffort, generate } from '@core-ai/core-ai';
import { createOpenAI, getOpenAIModelCapabilities } from '@core-ai/openai';

const openai = createOpenAI();
const model = openai.chatModel('gpt-5.2');

if (model.capabilities.reasoning.mode !== 'unsupported') {
    const effort = clampReasoningEffort(
        'medium',
        model.capabilities.reasoning.supportedEfforts
    );
    const temperature = model.capabilities.reasoning.restrictsSamplingParams
        ? undefined
        : 0.7;

    await generate({
        model,
        messages: [{ role: 'user', content: 'Think carefully.' }],
        reasoning: { effort },
        temperature,
    });
}

// Or look up capabilities without constructing a ChatModel:
const capabilities = getOpenAIModelCapabilities('gpt-5.2');

reasoning.mode is always-on for gpt-6.1-sol, gpt-6-astra, gpt-6-sol, and gpt-6-luna. Those models reason unless a Chat Completions request explicitly disables reasoning. Other OpenAI chat models are optional or unsupported. supportedEfforts lists the accepted effort levels, and supportedToolChoices contains all unified tool-choice modes. restrictsSamplingParams identifies models that reject temperature and topP while reasoning is enabled. OpenAI extends the shared capability shape with chatCompletions.maxTokensParameter. The Chat Completions adapter uses this to select max_tokens or max_completion_tokens; the Responses API is unaffected.

Image input

modalities.input is ['text', 'image', 'file'] for the GPT-4, GPT-5, and GPT-6 families, o1, o3, o3-pro, and o4-mini (image sources: base64 and url). It is ['text'] for gpt-3.5-turbo, o1-mini, and o3-mini. Model IDs outside the registry allow image and file input but do not advertise audio. modalities.output is ['text'] for all chat models.

Audio input

Audio input is available only through Chat Completions:

import { readFile } from 'fs/promises';

const audioData = (await readFile('recording.wav')).toString('base64');
const model = openai.chat.chatModel('gpt-audio-1.5');

const result = await generate({
    model,
    messages: [
        {
            role: 'user',
            content: [
                { type: 'text', text: 'Transcribe this recording' },
                {
                    type: 'audio',
                    source: {
                        type: 'base64',
                        mediaType: 'audio/wav',
                        data: audioData,
                    },
                },
            ],
        },
    ],
});

The audio model IDs listed above advertise modalities.input as ['text', 'audio'] on openai.chat.chatModel(). The adapter accepts audio/wav, audio/mp3, and audio/mpeg; both MP3 MIME types map to the native mp3 format. openai.chatModel() uses the Responses API, does not advertise audio, and rejects audio input with guidance to use Chat Completions. Unknown model IDs do not advertise audio. Output remains text-only. Reasoning support depends on the selected model family:

Models	Supported effort levels
`gpt-6.1-sol`, `gpt-6-astra`, `gpt-6-sol`, `gpt-6-luna`	`low`, `medium`, `high`, `max`
`gpt-5.6-sol`	`low`, `medium`, `high`, `max`
`gpt-5.6-terra`	`low`, `medium`, `high`
`gpt-5.6-luna`	`minimal`, `low`, `medium`, `high`
`gpt-5.5`, `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.4-nano`, `gpt-5.3-codex`, `gpt-5.2`, `gpt-5.2-codex`, `gpt-5.2-pro`	`low`, `medium`, `high`, `max`
`gpt-5.5-pro`, `gpt-5.4-pro`	`medium`, `high`, `max`
`gpt-5-pro`	`high`
`gpt-5.1`	`low`, `medium`, `high`
`gpt-5`, `gpt-5-mini`, `gpt-5-nano`	`minimal`, `low`, `medium`, `high`
`o3-pro`	`low`, `medium`, `high`, `max`
`o3`, `o3-mini`, `o4-mini`, `o1`	`low`, `medium`, `high`
`o1-mini`	No effort control

When capabilities.reasoning.restrictsSamplingParams is true, the adapter throws if you set temperature or topP while reasoning is enabled. GPT-6 models reason by default, so those parameters are rejected even when you omit reasoning.

For GPT-6, max is sent as max. For GPT-5 and o-series models, max is sent as xhigh. minimal on GPT-6 is clamped to low.GPT-6 Astra and GPT-6.1 Sol do not support tool calling on Chat Completions. Use chatModel() (the Responses API). GPT-6 Sol and Luna support Chat Completions function calling. The adapter forwards tools and reasoning as you set them, the same as GPT-5.6. OpenAI accepts function tools on these models only when the effective reasoning effort is none. Omitting reasoning leaves the provider default, medium.

Reasoning metadata

When reasoning is enabled on the Responses API, core-ai automatically requests encrypted reasoning content and exposes it through provider metadata under the 'openai' key. Wrappers such as Azure OpenAI use their own provider id (for example 'azure-openai') for the same ciphertext shape.

import { generate, getProviderMetadata } from '@core-ai/core-ai';
import type { OpenAIReasoningMetadata } from '@core-ai/openai';

const result = await generate({
    model: openai.chatModel('gpt-5.4'),
    messages: [{ role: 'user', content: 'Think carefully before answering.' }],
    reasoning: { effort: 'high' },
});

for (const part of result.parts) {
    if (part.type !== 'reasoning') continue;

    const metadata = getProviderMetadata<OpenAIReasoningMetadata>(
        part.providerMetadata,
        'openai'
    );

    console.log(metadata?.encryptedContent);
}

Provider-specific options

Options are namespaced under openai in providerOptions and validated with Zod schemas.

Generate options (Responses API)

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

const result = await generate({
    model: openai.chatModel('gpt-5-mini'),
    messages: [{ role: 'user', content: 'Hello' }],
    providerOptions: {
        openai: {
            store: true,
            serviceTier: 'auto',
            parallelToolCalls: true,
            user: 'user-123',
        },
    },
});

Available fields: store, serviceTier ('auto' | 'default' | 'flex' | 'scale' | 'priority'), include, parallelToolCalls, user, emulateToolDiscovery. emulateToolDiscovery renders tool discovery with ordinary functions on models that support it natively. See Tool discovery.

Responses requests default to store: false. If reasoning is enabled, core-ai also ensures reasoning.encrypted_content is included automatically.

Generate options (Chat Completions API)

When using openai.chat.chatModel(), the available options differ:

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

const result = await generate({
    model: openai.chat.chatModel('gpt-5-mini'),
    messages: [{ role: 'user', content: 'Hello' }],
    maxTokens: 1024,
    providerOptions: {
        openai: {
            store: true,
            serviceTier: 'auto',
            parallelToolCalls: true,
            stopSequences: ['\n\n'],
            frequencyPenalty: 0.5,
            presencePenalty: 0.3,
            seed: 42,
            user: 'user-123',
        },
    },
});

Chat Completions uses reasoning_effort instead of the Responses API reasoning payload shape. Chat Completions options do not support the include and emulateToolDiscovery fields.

Embed options

const result = await embed({
    model: openai.embeddingModel('text-embedding-3-small'),
    input: 'text to embed',
    providerOptions: {
        openai: {
            encodingFormat: 'float',
            user: 'user-123',
        },
    },
});

Image options

const result = await generateImage({
    model: openai.imageModel('gpt-image-1'),
    prompt: 'A cat',
    providerOptions: {
        openai: {
            quality: 'hd',
            style: 'vivid',
            responseFormat: 'url',
            background: 'auto',
            outputFormat: 'png',
        },
    },
});

Available fields: background, moderation, outputCompression, outputFormat, quality, responseFormat, style, user.

Error handling

import { ProviderError } from '@core-ai/core-ai';

try {
    const result = await generate({
        model: openai.chatModel('gpt-5-mini'),
        messages: [{ role: 'user', content: 'Hello!' }],
    });
} catch (error) {
    if (error instanceof ProviderError) {
        console.error('OpenAI API error:', error.message);
        console.error('Status:', error.statusCode);
    }
}

Anthropic Provider

Claude models with extended thinking

Google GenAI Provider

Gemini models with multimodal capabilities

core-ai Functions

Learn about generate, stream, and more

Core

Providers

OpenAI Provider

Overview

Installation

createOpenAI()

Options

Returns

Chat Completions

Provider methods

chatModel()

embeddingModel()

imageModel()

Supported models

Chat models

Embedding models

Image models

Examples

Basic chat

Reasoning with effort control

Embeddings

Image generation

Custom base URL

Model capabilities

Strict tool schemas

Tool discovery

Structured output schemas

Reasoning support

Image input

Audio input

Reasoning metadata

Provider-specific options

Generate options (Responses API)

Generate options (Chat Completions API)

Embed options

Image options

Error handling

Anthropic Provider

Google GenAI Provider

core-ai Functions

​Overview

​Installation

​createOpenAI()

​Options

​Returns

​Chat Completions

​Provider methods

​chatModel()

​embeddingModel()

​imageModel()

​Supported models

​Chat models

​Embedding models

​Image models

​Examples

​Basic chat

​Reasoning with effort control

​Embeddings

​Image generation

​Custom base URL

​Model capabilities

​Strict tool schemas

​Tool discovery

​Structured output schemas

​Reasoning support

​Image input

​Audio input

​Reasoning metadata

​Provider-specific options

​Generate options (Responses API)

​Generate options (Chat Completions API)

​Embed options

​Image options

​Error handling

​Related

Anthropic Provider

Google GenAI Provider

core-ai Functions

Overview

Installation

createOpenAI()

Options

Returns

Chat Completions

Provider methods

chatModel()

embeddingModel()

imageModel()

Supported models

Chat models

Embedding models

Image models

Examples

Basic chat

Reasoning with effort control

Embeddings

Image generation

Custom base URL

Model capabilities

Strict tool schemas

Tool discovery

Structured output schemas

Reasoning support

Image input

Audio input

Reasoning metadata

Provider-specific options

Generate options (Responses API)

Generate options (Chat Completions API)

Embed options

Image options

Error handling

Related