Embeddings

/**
 * Creates an embedding vector representing the input text
 * @param body - Embedding creation parameters
 * @param options - Optional request configuration
 * @returns Embedding response with vectors and usage information
 */
create(
  body: EmbeddingCreateParams,
  options?: RequestOptions
): APIPromise<CreateEmbeddingResponse>;

interface CreateEmbeddingResponse {
  /** The list of embeddings generated by the model. */
  data: Array<Embedding>;

  /** The name of the model used to generate the embedding. */
  model: string;

  /** The object type, which is always "list". */
  object: 'list';

  /** The usage information for the request. */
  usage: {
    /** The number of tokens used by the prompt. */
    prompt_tokens: number;

    /** The total number of tokens used by the request. */
    total_tokens: number;
  };
}

interface Embedding {
  /**
   * The embedding vector, which is a list of floats.
   * The length of the vector depends on the model.
   * - text-embedding-ada-002: 1536 dimensions
   * - text-embedding-3-small: 512 dimensions
   * - text-embedding-3-large: 3072 dimensions
   */
  embedding: Array<number>;

  /**
   * The index of the embedding in the list of embeddings.
   * Used to match embeddings with input texts when processing batches.
   */
  index: number;

  /** The object type, which is always "embedding". */
  object: 'embedding';
}

type EmbeddingModel =
  | 'text-embedding-ada-002'
  | 'text-embedding-3-small'
  | 'text-embedding-3-large';

interface EmbeddingCreateParams {
  /**
   * Input text to embed, encoded as a string or array of tokens.
   * To embed multiple inputs in a single request, pass an array of strings
   * or array of token arrays.
   *
   * Constraints:
   * - Per-input limit: 8192 tokens for all embedding models
   * - Array limit: 2048 dimensions or less
   * - Aggregate limit: 300,000 tokens maximum across all inputs in single request
   * - Cannot be empty string
   */
  input: string | Array<string> | Array<number> | Array<Array<number>>;

  /**
   * ID of the model to use for generating embeddings.
   * Must be an embedding model (text-embedding-3-small, etc.)
   * or a custom fine-tuned embedding model.
   */
  model: string & {} | EmbeddingModel;

  /**
   * The number of dimensions the resulting output embeddings should have.
   * Only supported in text-embedding-3 and later models.
   * Reduces dimensionality while maintaining semantic information.
   * Default: Full model dimensions
   */
  dimensions?: number;

  /**
   * The format to return the embeddings in.
   * - 'float': Standard floating-point array (default when specified)
   * - 'base64': Base64-encoded binary format for performance
   *
   * The client automatically decodes base64 to Float32Array by default.
   * Specify 'float' to get native float arrays if decoding is not needed.
   */
  encoding_format?: 'float' | 'base64';

  /**
   * A unique identifier representing your end-user, which can help
   * OpenAI to monitor and detect abuse.
   * Should be a user ID, session ID, or similar identifier.
   */
  user?: string;
}

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

const response = await client.embeddings.create({
  model: 'text-embedding-3-small',
  input: 'The quick brown fox jumped over the lazy dog',
});

console.log(`Generated embedding with ${response.data[0].embedding.length} dimensions`);
console.log(`Tokens used: ${response.usage.prompt_tokens}`);

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

const texts = [
  'Artificial intelligence is transforming industries',
  'Machine learning models require substantial training data',
  'Natural language processing enables text understanding',
];

const response = await client.embeddings.create({
  model: 'text-embedding-3-small',
  input: texts,
});

// Access embeddings by index
response.data.forEach((embedding) => {
  console.log(`Embedding ${embedding.index}: ${embedding.embedding.length}D vector`);
});

console.log(`Total tokens: ${response.usage.total_tokens}`);

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

const response = await client.embeddings.create({
  model: 'text-embedding-3-large',
  input: 'Sample text for embedding',
  dimensions: 256, // Reduce from 3072 to 256 dimensions
});

console.log(`Reduced embedding size: ${response.data[0].embedding.length} dimensions`);

import OpenAI from 'openai';

interface Document {
  id: string;
  content: string;
  embedding: number[];
}

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

async function embedDocuments(
  docs: Array<{ id: string; content: string }>
): Promise<Document[]> {
  // Batch embed all documents
  const response = await client.embeddings.create({
    model: 'text-embedding-3-small',
    input: docs.map((doc) => doc.content),
  });

  // Combine with original documents
  return docs.map((doc, idx) => ({
    id: doc.id,
    content: doc.content,
    embedding: response.data[idx].embedding,
  }));
}

// Store in vector database
const documents: Document[] = await embedDocuments([
  { id: 'doc1', content: 'Sample document one' },
  { id: 'doc2', content: 'Sample document two' },
  { id: 'doc3', content: 'Sample document three' },
]);

// Example: Similarity search
async function findSimilar(query: string, topK: number = 3): Promise<Document[]> {
  const queryResponse = await client.embeddings.create({
    model: 'text-embedding-3-small',
    input: query,
  });

  const queryEmbedding = queryResponse.data[0].embedding;

  // Calculate cosine similarity
  function cosineSimilarity(a: number[], b: number[]): number {
    const dotProduct = a.reduce((sum, val, i) => sum + val * b[i], 0);
    const magnitudeA = Math.sqrt(a.reduce((sum, val) => sum + val * val, 0));
    const magnitudeB = Math.sqrt(b.reduce((sum, val) => sum + val * val, 0));
    return dotProduct / (magnitudeA * magnitudeB);
  }

  // Score and sort documents
  const scored = documents.map((doc) => ({
    doc,
    score: cosineSimilarity(queryEmbedding, doc.embedding),
  }));

  return scored
    .sort((a, b) => b.score - a.score)
    .slice(0, topK)
    .map((item) => item.doc);
}

const results = await findSimilar('machine learning algorithms');
console.log('Similar documents:', results);

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

// Request embeddings as native float arrays
const response = await client.embeddings.create({
  model: 'text-embedding-3-small',
  input: 'Sample text',
  encoding_format: 'float', // Get raw float arrays
});

const embedding = response.data[0].embedding;
console.log(`Embedding type: ${embedding.constructor.name}`);
console.log(`First 5 values: ${embedding.slice(0, 5)}`);

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

const response = await client.embeddings.create({
  model: 'text-embedding-3-small',
  input: 'Content to embed',
  user: 'user-12345', // Track usage per user
});

console.log(`Generated embedding for user: user-12345`);

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

try {
  const response = await client.embeddings.create({
    model: 'text-embedding-3-small',
    input: largeTextArray, // May exceed token limits
  });
} catch (error) {
  if (error instanceof OpenAI.RateLimitError) {
    console.error('Rate limit exceeded, retry after delay');
  } else if (error instanceof OpenAI.BadRequestError) {
    console.error('Invalid input (empty string or token limit exceeded)');
  } else {
    console.error('Unexpected error:', error);
  }
}