Embeddings

Endpoint

POST /v1/embeddings

Request Body

| Field | Type | Required | Description | |---|---|---|---| | model | string | yes | Embedding model to use. There is no default — you must specify a model. See supported models below. | | input | string | string[] | yes | Text to embed. Pass a single string or an array of strings for batch embedding. | | encoding_format | string | no | Output format. Currently "float" is supported. | | dimensions | number | no | Number of dimensions for the output vector. Supported by select models. |

Model is required

Unlike the chat endpoint, model has no "auto" default for embeddings. You must explicitly choose a model that matches your use case — different models are not interchangeable as their vector spaces are incompatible.

Supported Models

| Provider | Example Models | Notes | |---|---|---| | Cloudflare Workers AI | @cf/baai/bge-small-en-v1.5, @cf/baai/bge-base-en-v1.5, @cf/baai/bge-large-en-v1.5 | General-purpose English embeddings | | Google Gemini | gemini-embedding-001 (text-embedding-004, text-embedding-3-small, and text-embedding-3-large aliases) | Multilingual, supports requested dimensions | | Voyage AI | voyage-3.5-lite, voyage-3-lite | Domain-specialised embeddings |

Use GET /v1/models to get the full current list with provider metadata, dimensions, aliases, and enabled availability based on configured provider credentials/bindings.

Response

The response follows the standard OpenAI embeddings format:

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.0023, -0.0089, 0.0412, ...]
    }
  ],
  "model": "voyage-3",
  "usage": {
    "prompt_tokens": 8,
    "total_tokens": 8
  }
}

For batch inputs, data contains one entry per input string, in the same order.

Examples

Single String

curl

curl https://your-gateway.workers.dev/v1/embeddings \
  -H "Authorization: Bearer <GATEWAY_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "voyage-3",
    "project_id": "my_project",
    "input": "The quick brown fox jumps over the lazy dog"
  }'

JavaScript

const response = await fetch('https://your-gateway.workers.dev/v1/embeddings', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <GATEWAY_API_KEY>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'voyage-3',
    input: 'The quick brown fox jumps over the lazy dog',
  }),
});

const data = await response.json();
const vector = data.data[0].embedding;
console.log(`Embedding dimensions: ${vector.length}`);

Batch Embedding

curl

curl https://your-gateway.workers.dev/v1/embeddings \
  -H "Authorization: Bearer <GATEWAY_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "@cf/baai/bge-base-en-v1.5",
    "project_id": "my_project",
    "input": [
      "How do I reset my password?",
      "Where can I find my invoice?",
      "How do I cancel my subscription?"
    ]
  }'

JavaScript

const texts = [
  'How do I reset my password?',
  'Where can I find my invoice?',
  'How do I cancel my subscription?',
];

const response = await fetch('https://your-gateway.workers.dev/v1/embeddings', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <GATEWAY_API_KEY>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: '@cf/baai/bge-base-en-v1.5',
    input: texts,
  }),
});

const data = await response.json();
const embeddings = data.data.map((item) => item.embedding);
console.log(`Got ${embeddings.length} vectors of length ${embeddings[0].length}`);

With Dimensions (Gemini)

curl

curl https://your-gateway.workers.dev/v1/embeddings \
  -H "Authorization: Bearer <GATEWAY_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-004",
    "project_id": "my_project",
    "input": "Semantic search query",
    "dimensions": 256
  }'

JavaScript

const response = await fetch('https://your-gateway.workers.dev/v1/embeddings', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <GATEWAY_API_KEY>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'text-embedding-004',
    input: 'Semantic search query',
    dimensions: 256,
  }),
});

const data = await response.json();
console.log(data.data[0].embedding.length); // 256

OpenAI SDK

The gateway is fully compatible with the OpenAI Node.js SDK:

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://your-gateway.workers.dev/v1',
  apiKey: '<GATEWAY_API_KEY>',
});

const result = await client.embeddings.create({
  model: 'voyage-3-lite',
  input: ['cat', 'dog', 'fish'],
});

result.data.forEach((item, i) => {
  console.log(`Text ${i}: ${item.embedding.length} dims`);
});