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-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’s reasoning constraints. The exported getOpenAIModelCapabilities(modelId) helper returns the same data without constructing a model.

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');

OpenAI reasoning is not always on. 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 and GPT-5 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-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 (GPT-5 family models), the adapter throws if you set temperature or topP while reasoning is enabled.

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.

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 include field.

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

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

​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

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