> ## Documentation Index
> Fetch the complete documentation index at: https://docs.core-ai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Models

> Understanding chat models, embedding models, and image models in core-ai

## Overview

core-ai supports three types of models, each designed for specific tasks:

* **Chat Models**: Generate text responses, support conversations with tool calling
* **Embedding Models**: Convert text into vector representations for semantic search
* **Image Models**: Generate images from text prompts

## Chat Models

Chat models are the most versatile, supporting text generation, conversations, tool calling, and structured output.

### Interface

```typescript theme={null}
type ChatModel = {
    readonly provider: string;
    readonly modelId: string;
    readonly capabilities: ModelCapabilities;
    generate(options: GenerateOptions): Promise<GenerateResult>;
    stream(options: GenerateOptions): Promise<ChatStream>;
    generateObject<TSchema extends z.ZodType>(
        options: GenerateObjectOptions<TSchema>
    ): Promise<GenerateObjectResult<TSchema>>;
    streamObject<TSchema extends z.ZodType>(
        options: StreamObjectOptions<TSchema>
    ): Promise<ObjectStream<TSchema>>;
};
```

### Basic Text Generation

```typescript theme={null}
import { createOpenAI } from '@core-ai/openai';
import { generate } from '@core-ai/core-ai';

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

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

console.log(result.content);
// "Quantum computing uses quantum bits that can exist in multiple states..."
```

### Streaming Responses

```typescript theme={null}
import { stream } from '@core-ai/core-ai';

const response = await stream({
    model,
    messages: [{ role: 'user', content: 'Write a short story.' }],
});

for await (const event of response) {
    if (event.type === 'text-delta') {
        process.stdout.write(event.text);
    }
}
```

### Structured Output

Generate type-safe structured data using Zod schemas:

```typescript theme={null}
import { z } from 'zod';
import { generateObject } from '@core-ai/core-ai';

const schema = z.object({
    name: z.string(),
    age: z.number(),
    hobbies: z.array(z.string()),
});

const result = await generateObject({
    model,
    messages: [{ role: 'user', content: 'Generate a random person profile.' }],
    schema,
    schemaName: 'Person',
});

console.log(result.object);
// { name: "Alice Smith", age: 28, hobbies: ["reading", "hiking"] }
```

### Tool Calling

Extend model capabilities with function tools:

```typescript theme={null}
import { defineTool } from '@core-ai/core-ai';
import { z } from 'zod';

const tools = {
    getWeather: defineTool({
        name: 'getWeather',
        description: 'Get current weather for a location',
        parameters: z.object({
            location: z.string().describe('City name'),
            unit: z.enum(['celsius', 'fahrenheit']).optional(),
        }),
    }),
};

const result = await generate({
    model,
    messages: [{ role: 'user', content: "What's the weather in Paris?" }],
    tools,
});

if (result.toolCalls.length > 0) {
    console.log(result.toolCalls[0]);
    // { id: "call_123", name: "getWeather", arguments: { location: "Paris" } }
}
```

### Generate result

`generate()` returns a `GenerateResult` with `parts`, `content`, `reasoning`, `toolCalls`, `finishReason`, and `usage`.

### Stream events

`stream()` returns a replayable `ChatStream` that emits reasoning, text, tool-call, and `finish` events while also exposing `.result` and `.events`.

See the [types reference](/api/core/types) for the full `GenerateResult`, `StreamEvent`, and `FinishReason` type definitions.

## Embedding Models

Embedding models convert text into numerical vectors for semantic similarity and search.

### Interface

```typescript theme={null}
type EmbeddingModel = {
    readonly provider: string;
    readonly modelId: string;
    embed(options: EmbedOptions): Promise<EmbedResult>;
};
```

### Basic Usage

```typescript theme={null}
import { embed } from '@core-ai/core-ai';
import { createOpenAI } from '@core-ai/openai';

const openai = createOpenAI();
const model = openai.embeddingModel('text-embedding-3-small');

const result = await embed({
    model,
    input: 'The quick brown fox jumps over the lazy dog',
});

console.log(result.embeddings[0].length);
// 1536 (dimensions)
```

### Batch Embedding

```typescript theme={null}
const result = await embed({
    model,
    input: ['First document', 'Second document', 'Third document'],
});

console.log(result.embeddings.length);
// 3
```

### Custom Dimensions

```typescript theme={null}
const result = await embed({
    model,
    input: 'Sample text',
    dimensions: 256, // Reduce dimensions for faster search
});
```

### Embed Result

```typescript theme={null}
type EmbedResult = {
    embeddings: number[][]; // Array of embedding vectors
    usage?: EmbeddingUsage; // Optional token usage (provider-dependent)
};

type EmbeddingUsage = {
    inputTokens: number;
};
```

## Image Models

Image models generate images from text descriptions.

### Interface

```typescript theme={null}
type ImageModel = {
    readonly provider: string;
    readonly modelId: string;
    generate(options: ImageGenerateOptions): Promise<ImageGenerateResult>;
};
```

### Basic Usage

```typescript theme={null}
import { generateImage } from '@core-ai/core-ai';
import { createOpenAI } from '@core-ai/openai';

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

const result = await generateImage({
    model,
    prompt: 'A futuristic city at sunset with flying cars',
});

console.log(result.images[0]);
// { base64: "...", revisedPrompt: "..." }
```

### Generate Options

```typescript theme={null}
type ImageGenerateOptions = {
    prompt: string; // Text description of desired image
    n?: number; // Number of images to generate
    size?: string; // Image size (e.g., "1024x1024")
    providerOptions?: ImageProviderOptions; // Provider-specific options
};
```

### Multiple Images

```typescript theme={null}
const result = await generateImage({
    model,
    prompt: 'Abstract art with geometric shapes',
    n: 4, // Generate 4 variations
    size: '512x512',
});

console.log(result.images.length);
// 4
```

### Image Result

```typescript theme={null}
type ImageGenerateResult = {
    images: GeneratedImage[];
};

type GeneratedImage = {
    base64?: string; // Base64-encoded image data
    url?: string; // URL to hosted image
    revisedPrompt?: string; // Provider-revised prompt
};
```

<Note>
  Different providers may return images as URLs, base64 data, or both. Check
  the provider documentation for specific behavior.
</Note>

## Model Properties

All models expose readonly `provider` and `modelId` properties:

```typescript theme={null}
const model = openai.chatModel('gpt-5-mini');

console.log(model.provider); // "openai"
console.log(model.modelId); // "gpt-5-mini"
```

These properties are useful for logging, debugging, and tracking which models are used in your application.

### Chat model capabilities

Chat models also expose a `capabilities` property that describes what the model supports for the unified API. Use it to decide whether to pass `reasoning` and which effort levels are valid before making a request:

```typescript theme={null}
const model = openai.chatModel('gpt-5.2');

if (model.capabilities.reasoning.supported) {
    console.log(model.capabilities.reasoning.supportedEfforts);
    // ['low', 'medium', 'high', 'max']

    // When true, omit temperature/topP while reasoning is enabled
    console.log(model.capabilities.reasoning.restrictsSamplingParams);
}
```

Provider packages also export `get*ModelCapabilities(modelId)` helpers (for example `getOpenAIModelCapabilities`) that return the same data without constructing a `ChatModel`. See the [types reference](/api/core/types) for the full `ModelCapabilities` definition and [`clampReasoningEffort`](/api/core/utilities) for adjusting an effort level to the supported set.

## Next steps

* Learn about [Messages](/concepts/messages) to structure conversations
* Configure models with [Configuration](/concepts/configuration) options
* Extend models with [Middleware](/concepts/middleware) for logging, validation, and more
* Handle errors with [Error Handling](/concepts/error-handling)