<!-- BusyBot node reference — https://busybot.net/tools/openai-embeddings/ -->

> Node: OpenAI Embeddings (`openai_embeddings`) · Action · v1
> Category: AI · Credentials: OpenAI (`openai`)
> Updated: 2026-08-16

# OpenAI Embeddings

> Generate vector embeddings using OpenAI embedding models.

## Overview

OpenAI Embeddings uses the Embeddings API (POST /embeddings) to generate dense vector representations of text. The Model dropdown lists the OpenAI embedding models currently available to the workspace, trading vector quality against cost and storage size. Configurable output dimensions for the v3 embedding models. Each input item produces a float embedding vector placed in a configurable output field, along with model and usage metadata.

**Category:** AI  
**Tool Name:** `openai_embeddings`  
**Version:** 1

**Appearance:** Icon: `openai` | Color: `#10a37f`

## Node Type

**Action** — processes input items and produces output

## Input / Output

| Direction | Port(s) |
|-----------|--------|
| Input | `Input` |
| Output | `Output`, `Error` |

## Credentials

This tool requires **OpenAI** credentials.
See the [Credentials Guide](https://busybot.net/credentials/openai/) for setup instructions.

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Model | `options` | No | (current default) | The OpenAI embedding model to use. Always uses the latest version (auto-updated). |
| | | | | Options: the OpenAI embedding models available to your workspace — pick one from the dropdown. |
| Text | `string` | Yes | — | The text to generate an embedding for. If empty, falls back to item.json.text. Supports expressions. |
| Options | `collection` | No | `{}` | Optional embedding settings — add only the fields you need. |
| — Dimensions | `number` | No | — | Output vector dimensions. Supported by the v3 embedding models; older non-v3 models ignore it. Lower values reduce storage cost with minimal quality loss. |
| — Response Field Name | `string` | No | `embedding` | Field name in the output JSON where the embedding vector will be placed. |
| Include Input | `boolean` | No | `false` | Whether to include the original input item fields in the output alongside the embedding. |
| Max Concurrency | `number` | No | `10` | Maximum number of items to process concurrently. |

## Output Data

One output item per input item. The vector lands on the field named by **Response Field Name** (`embedding` by default), with `model` and `usage` beside it. The rest of the input item JSON is dropped unless **Include Input** is on; binary data on the input item is forwarded unchanged.

```json
{
  "embedding": [0.0123, -0.0456, 0.0789],
  "model": "the embedding model that was used",
  "usage": { "prompt_tokens": 12, "total_tokens": 12 }
}
```

- The vector is a plain array of floats. Its length is the model's native size unless you set **Dimensions**.
- Turn **Include Input** on when you are writing vectors to a store and need the source text or an ID to travel with them.

Reference the result downstream by expression, e.g. `{{ $json.embedding }}`.

## Usage Examples

- Generate embeddings for text chunks for vector search
- Embed product descriptions for similarity lookup
- Create reduced-dimension vectors to cut storage cost
- Vectorize documents for semantic similarity comparison
- Embed search queries for nearest-neighbor lookup

## Example Configuration

Embed the text field of each incoming item:

```json
{
  "type": "openai_embeddings",
  "parameters": {
    "text": "{{ $json.text }}"
  }
}
```

Embed document chunks at reduced dimensions, keeping the source fields:

```json
{
  "type": "openai_embeddings",
  "parameters": {
    "text": "{{ $json.chunk }}",
    "includeInput": true,
    "maxConcurrency": 20,
    "options": {
      "dimensions": 256,
      "responseFieldName": "vector"
    }
  }
}
```

### Error Handling

| Mode | Behavior |
|------|----------|
| **stop** | Halts workflow on first error |
| **continue** | Skips failed items, passes successful ones through |
| **errorPort** | Routes failed items to Error output port |

## Tips

OpenAI Embeddings converts text into dense float vectors using whichever OpenAI embedding model is picked in the Model dropdown. Use it when your workflow requires semantic search, similarity matching, or retrieval-augmented generation that depends on vector representations of text. Each input produces a float embedding vector written to a configurable output field, plus model name and token usage metadata on the main output.