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-base-en-v1.5, @cf/baai/bge-large-en-v1.5	General-purpose English embeddings
Google Gemini	text-embedding-004, embedding-001	Multilingual, supports dimensions
Voyage AI	voyage-3, voyage-3-lite, voyage-code-3, voyage-finance-2	Domain-specialised, high accuracy

Use GET /v1/models to get the full current list with provider metadata.

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",
    "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",
    "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",
    "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`);
});