Quickstart

Get up and running with core-ai in just a few minutes. This guide shows you how to create a simple chat completion using OpenAI’s GPT model.

Prerequisites

Before you begin, make sure you have:

Node.js 22 or higher installed
An OpenAI API key (get one here)
Completed the installation steps

Create your first chat completion

Set up your project

Create a new file called chat.ts in your project:

touch chat.ts

Make sure you have your API key set as an environment variable:

export OPENAI_API_KEY="your-api-key-here"

Import dependencies

Add the necessary imports to your chat.ts file:

chat.ts

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

The generate function handles chat completions, while createOpenAI initializes the OpenAI provider.

Initialize the provider and model

Create an OpenAI provider instance and select a chat model:

chat.ts

const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY });
const model = openai.chatModel('gpt-5-mini');

You can use any OpenAI model ID like gpt-5.4, gpt-5-mini, gpt-5, or o3-mini.

Generate a response

Call the generate function with your model and messages:

chat.ts

const result = await generate({
  model,
  messages: [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'Explain quantum computing in one sentence.' },
  ],
});

console.log(result.content);
console.log('Usage:', result.usage);

Run your code

Execute your script using tsx:

npx tsx chat.ts

You should see the AI’s response printed to the console along with token usage statistics.

Complete example

Here’s the full working example:

chat.ts

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

const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY });
const model = openai.chatModel('gpt-5-mini');

const result = await generate({
  model,
  messages: [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'Explain quantum computing in one sentence.' },
  ],
});

console.log('Response:', result.content);
console.log('Usage:', result.usage);
// Output:
// Response: Quantum computing uses quantum mechanical phenomena...
// Usage: { inputTokens: 25, outputTokens: 18, inputTokenDetails: { ... }, outputTokenDetails: { ... } }

Try streaming

core-ai makes streaming responses just as easy. Here’s how to stream text as it’s generated:

streaming.ts

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

const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY });
const model = openai.chatModel('gpt-5-mini');

const result = await stream({
  model,
  messages: [
    { role: 'user', content: 'Write a short haiku about TypeScript.' },
  ],
});

// Stream each text chunk as it arrives
for await (const event of result) {
  if (event.type === 'text-delta') {
    process.stdout.write(event.text);
  }
}

// Get the complete response with metadata
const response = await result.result;
console.log('\nFinish reason:', response.finishReason);
console.log('Usage:', response.usage);

The .result property returns a promise that resolves with the aggregated GenerateResult once the stream completes. Streams are replayable — you can iterate multiple times.

Switch providers

One of core-ai’s key features is provider portability. Switch from OpenAI to Anthropic with just two lines:

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

const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY });
const model = openai.chatModel('gpt-5-mini');

const result = await generate({
  model,
  messages: [{ role: 'user', content: 'Hello!' }],
});

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

const anthropic = createAnthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
const model = anthropic.chatModel('claude-haiku-4-5');

const result = await generate({
  model,
  messages: [{ role: 'user', content: 'Hello!' }],
});

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

const google = createGoogleGenAI({ apiKey: process.env.GOOGLE_API_KEY });
const model = google.chatModel('gemini-3.1-pro');

const result = await generate({
  model,
  messages: [{ role: 'user', content: 'Hello!' }],
});

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

const mistral = createMistral({ apiKey: process.env.MISTRAL_API_KEY });
const model = mistral.chatModel('mistral-large-2512');

const result = await generate({
  model,
  messages: [{ role: 'user', content: 'Hello!' }],
});

Next steps

Now that you have a working chat completion, explore more advanced features:

Structured outputs

Generate type-safe JSON objects with Zod schemas

Tool calling

Let AI call functions with validated parameters

Embeddings

Generate vector embeddings for semantic search

Image generation

Create images from text prompts

Get Started

Core Concepts

Guides

Observability

Examples

Quickstart

Quickstart

Prerequisites

Create your first chat completion

Complete example

Try streaming

Switch providers

Next steps

Structured outputs

Tool calling

Embeddings

Image generation

​Quickstart

​Prerequisites

​Create your first chat completion

​Complete example

​Try streaming

​Switch providers

​Next steps

Structured outputs

Tool calling

Embeddings

Image generation

Quickstart

Prerequisites

Create your first chat completion

Complete example

Try streaming

Switch providers

Next steps