Skip to main content

​
Overview

The OpenAI provider gives you access to GPT-5 models, o-series reasoning models, embeddings, and image generation. By default, createOpenAI uses the Responses API. For the Chat Completions API, use createOpenAICompat from @core-ai/openai/compat.

​
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

​
apiKey
string
Your OpenAI API key. Defaults to OPENAI_API_KEY environment variable.
​
baseURL
string
Custom base URL for API requests. Useful for proxies or OpenAI-compatible APIs.
​
client
OpenAI
Provide your own configured OpenAI client instance.

​
Returns

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

​
createOpenAICompat()

Create an OpenAI provider instance using the Chat Completions API. 
import { createOpenAICompat } from '@core-ai/openai/compat';

const openai = createOpenAICompat({
    apiKey: process.env.OPENAI_API_KEY,
});
Same options as createOpenAI. Returns OpenAICompatProvider with the same model factory methods. Use createOpenAICompat when you need Chat Completions API compatibility, for example with third-party OpenAI-compatible endpoints.

​
Provider methods

​
chatModel()

const model = openai.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.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
  • 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
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',
});

​
Reasoning support

Inspect model capabilities 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.supported) {
    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 support depends on the selected model family:
ModelsSupported effort levels
gpt-5.6-sollow, medium, high, max
gpt-5.6-terralow, medium, high
gpt-5.6-lunaminimal, 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-prolow, medium, high, max
gpt-5.5-pro, gpt-5.4-promedium, high, max
gpt-5-prohigh
gpt-5.1low, medium, high
gpt-5, gpt-5-mini, gpt-5-nanominimal, low, medium, high
o3-prolow, medium, high, max
o3, o3-mini, o4-mini, o1low, medium, high
o1-miniNo 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. 
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 createOpenAICompat, the available options differ: 
import { createOpenAICompat } from '@core-ai/openai/compat';
import { generate } from '@core-ai/core-ai';

const openai = createOpenAICompat();

const result = await generate({
    model: openai.chatModel('gpt-5-mini'),
    messages: [{ role: 'user', content: 'Hello' }],
    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. The compat options do not support the 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