embed

API reference for the embed function

Embeds a single value using an embedding model.

import { embed } from 'ai';
import { openai } from '@ai-sdk/openai';

const result = await embed({
  model: openai.embedding('text-embedding-3-small'),
  value: 'sunny day at the beach',
});

console.log(result.embedding);

Parameters

model · EmbeddingModel · required

The embedding model to use.

value · string · required

The value that should be embedded.

maxRetries · number · default: "2"

Maximum number of retries per embedding model call. Set to 0 to disable retries.

abortSignal · AbortSignal

Abort signal for canceling the embedding request.

headers · Record<string, string>

Additional headers to include in the request. Only applicable for HTTP-based providers.

providerOptions · ProviderOptions

Additional provider-specific options. They are passed through to the provider from the AI SDK and enable provider-specific functionality that can be fully encapsulated in the provider.

experimental_telemetry · TelemetrySettings

Optional telemetry configuration (experimental).

Returns

value · string

The value that was embedded.

embedding · number[]

The embedding vector as an array of numbers.

usage · { tokens: number }

The token usage for the embedding operation.

warnings · Array<CallWarning>

Warnings from the embedding model provider (e.g., unsupported settings).

providerMetadata · ProviderMetadata

Additional provider-specific metadata.

response · EmbeddingModelResponseMetadata

Response metadata from the embedding model.

Examples

Basic embedding

import { embed } from 'ai';
import { openai } from '@ai-sdk/openai';

const result = await embed({
  model: openai.embedding('text-embedding-3-small'),
  value: 'sunny day at the beach',
});

console.log(result.embedding);
// [0.123, -0.456, 0.789, ...]

With usage tracking

import { embed } from 'ai';
import { openai } from '@ai-sdk/openai';

const result = await embed({
  model: openai.embedding('text-embedding-3-small'),
  value: 'sunny day at the beach',
});

console.log('Tokens used:', result.usage.tokens);
console.log('Embedding dimensions:', result.embedding.length);

Multiple embeddings

For embedding multiple values efficiently, use embedMany instead:

import { embedMany } from 'ai';
import { openai } from '@ai-sdk/openai';

const result = await embedMany({
  model: openai.embedding('text-embedding-3-small'),
  values: [
    'sunny day at the beach',
    'rainy day in the mountains',
    'snowy day in the city',
  ],
});

console.log(result.embeddings);