Embeddings reference

Purpose and Scope

Embeddings turn text into numerical vectors that downstream search, retrieval, clustering, recommendation, classification, and anomaly detection systems can compare. In this SDK, the embeddings surface is intentionally small: a caller creates an OpenAI client, calls the embeddings resource with input text and an embedding model, and receives a list response containing one or more vectors plus usage metadata. This page focuses on the TypeScript and JavaScript contract exposed by the generated client, including request options, response objects, encoding behavior, and the test fixtures that lock in float and base64 handling.

Sources: src/resources/embeddings.ts, tests/api-resources/embeddings.test.ts, tests/api-resources/embeddings-float-response.json

Relevant Source Files

• api.md - Generated SDK API reference companion for the public embeddings surface and exported types.
• src/resources/embeddings.ts - Implements the embeddings resource, request method, response interfaces, model union, authentication flag, and encoding-format transform.
• tests/api-resources/embeddings.test.ts - Exercises required parameters, optional parameters, response helper methods, and default, float, and base64 encoding behavior.
• tests/api-resources/embeddings-float-response.json - Fixture captured from a live API-style embedding response with numeric vector values and usage metadata.

Sources: api.md, src/resources/embeddings.ts, tests/api-resources/embeddings.test.ts, tests/api-resources/embeddings-float-response.json

Public API and Request Contract

The public entry point is the embeddings resource on an initialized OpenAI client. The resource class extends the shared API resource base and exposes a single create method that returns an API promise for a create embedding response. The implementation sends a POST request to the embeddings endpoint and marks the request as using bearer authentication. The method also accepts request options, so callers can apply the same per-request configuration patterns used elsewhere in the SDK, such as custom timeout, retry, headers, or signal behavior when those options are supported by the core client.

Sources: src/resources/embeddings.ts

The required request fields demonstrated by the tests are input and model. The examples use a sentence as input and the small text embedding model as the model value. The optional parameters covered by the tests are dimensions, encoding format, and user. The resource source also exports an embedding model union containing the ada model and both third-generation small and large embedding models. That means application code can rely on generated TypeScript names for common model identifiers while still treating the method as a direct representation of the REST API request body.

Sources: src/resources/embeddings.ts, tests/api-resources/embeddings.test.ts

Response Shape and Encoding Formats

The create response is a list object with data, model, object, and usage fields. Each data item represents a single embedding, carries the index of the input item it corresponds to, and has an object type of embedding. Usage includes prompt token and total token counts, which are important when embedding large corpora or building retrieval pipelines that batch many documents. The float fixture shows this complete shape: a list containing one embedding at index zero, the model name, and a usage object with one prompt token and one total token.

Sources: src/resources/embeddings.ts, tests/api-resources/embeddings-float-response.json

Encoding behavior is the most important SDK-specific detail on this page. If the caller does not provide an encoding format, the SDK sends base64 to the API for performance reasons, then decodes the returned base64 embedding values before resolving the promise. The result observed by the default test is a numeric array with float precision values. If the caller explicitly provides an encoding format, the SDK returns the API response as-is. Explicit float therefore returns numeric values, while explicit base64 returns string embedding values in the response data.

Sources: src/resources/embeddings.ts, tests/api-resources/embeddings.test.ts

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: 'Your text string goes here',
  encoding_format: 'float',
});
 
const vector = response.data[0].embedding;
console.log(response.model, vector.length, response.usage.total_tokens);

Execution Flow

When create is called, the method first checks whether the request body already contains an encoding format. If one is present, the resource logs that the user selected it and preserves that choice. If not, it builds a request body that adds base64 as the encoding format. The POST request is then issued with the merged body and any caller-provided request options. This means callers do not need to opt into base64 transport to receive efficient default behavior; the resource handles the transport optimization internally before returning application-facing data.

Sources: src/resources/embeddings.ts

After the HTTP request is created, the method branches again based on whether the caller supplied an encoding format. User-specified formats are never rewritten on the way back, which is why explicit base64 can be used by applications that want to store compact strings or perform their own decoding. For the default path, the API promise is unwrapped and each returned embedding value is converted from the base64 string into numeric vector data. This makes the default ergonomic for typical machine learning and vector database workflows that expect arrays of numbers.

Sources: src/resources/embeddings.ts, tests/api-resources/embeddings.test.ts

Testing Signals and Fixtures

The embeddings tests verify both the ordinary resource contract and the encoding edge cases. The required-parameters test awaits the API promise in three different ways: as a raw response, as parsed data, and as data paired with the response object. This confirms that embeddings participate in the SDK promise helper model rather than returning a plain fetch response. A second test sends dimensions, encoding format, and user together to ensure optional request fields are accepted by the generated resource method.

Sources: tests/api-resources/embeddings.test.ts

The encoding tests use a mock fetch client that inspects the serialized request body. When the body encoding format is base64, the test server returns the base64 fixture; otherwise it returns the float fixture. The default request does not pass an encoding format, but the SDK adds base64 internally, receives the base64 fixture, decodes it, and exposes a numeric first value. The explicit float test returns a numeric first value directly from the float fixture. The explicit base64 test asserts that the embedding value remains a string.

Sources: tests/api-resources/embeddings.test.ts, tests/api-resources/embeddings-float-response.json

Practical Usage Guidance

For semantic search or retrieval augmented generation, a common workflow is to split documents into reasonably sized text chunks, call the embeddings endpoint for each chunk or batch, and store the returned vectors beside the original text and metadata. At query time, embed the user question and compare that vector to stored document vectors with a distance or similarity measure. The SDK does not choose the vector database or distance function for you; it supplies the typed API surface and response values that those systems consume.

Sources: src/resources/embeddings.ts, tests/api-resources/embeddings-float-response.json

Choose explicit float encoding when you want the request and response shape to match the public API examples exactly and you prefer direct numeric JSON values. Leave the encoding format unset when you want the SDK default, which optimizes the transport representation and still resolves to numeric vector values for normal application use. Choose explicit base64 only when your application intentionally wants encoded strings, for example to preserve compact serialized embeddings or to hand decoding responsibility to another component. Tests cover all three modes, so regressions in this behavior should be visible quickly.

Sources: src/resources/embeddings.ts, tests/api-resources/embeddings.test.ts

Next Steps

Use this page as the method-level reference for creating embeddings through openai-node. If you are building an end-user application, pair it with the quickstart to review client construction and environment variables, then read the vector stores and file search pages for hosted retrieval workflows. If you are implementing your own search index, focus on the response shape, usage accounting, and encoding choice described here, then add application tests that assert the vector length, model, and metadata your pipeline expects.

Sources: api.md, src/resources/embeddings.ts, tests/api-resources/embeddings.test.ts