Embeddings

Embeddings turns text into vectors: lists of numbers that capture meaning, so that passages about the same idea end up close together even when they share no words. Store them in a vector database and you can build semantic search, retrieval-augmented generation (RAG), clustering, deduplication and recommendations on top. If the idea is new to you, Embeddings: How AI Understands Meaning explains it from the ground up. POST /ai/v2/direct/embeddings serves every embedding model in the Gloo catalog (OpenAI, Google, Voyage AI, Mistral, Qwen, BAAI and more) behind one request shape. The request and response mirror the OpenAI Embeddings API, so the OpenAI SDKs work by pointing the base URL at Gloo.

You don’t need this endpoint to search content you have uploaded to Gloo. The Data Engine embeds your content for you, and Search and the grounded endpoints query it. Use Embeddings when you run your own vector store.

Quick start

URL: https://platform.ai.gloo.com/ai/v2/direct/embeddings Operation: POST

curl -X POST 'https://platform.ai.gloo.com/ai/v2/direct/embeddings' \
  -H "Authorization: Bearer ${GLOO_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gloo-openai-text-embedding-3-small",
    "input": ["In the beginning was the Word.", "Love is patient."]
  }'

Authentication is the same as the rest of the platform: send your API key as a Bearer token. See Generate API Keys.

With the OpenAI SDK

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["GLOO_API_KEY"],
    base_url="https://platform.ai.gloo.com/ai/v2/direct",
)

result = client.embeddings.create(
    model="gloo-openai-text-embedding-3-small",
    input=["In the beginning was the Word.", "Love is patient."],
)

for item in result.data:
    print(item.index, len(item.embedding))

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.GLOO_API_KEY,
  baseURL: 'https://platform.ai.gloo.com/ai/v2/direct',
});

const result = await client.embeddings.create({
  model: 'gloo-openai-text-embedding-3-small',
  input: ['In the beginning was the Word.', 'Love is patient.'],
});

for (const item of result.data) {
  console.log(item.index, item.embedding.length);
}

Request format

Parameter	Type	Required?	Description
`model`	string	Yes	An embedding model’s Gloo Model ID, e.g. `gloo-openai-text-embedding-3-small`. See Choosing a model.
`input`	string \| array of strings	Yes	The text to embed: one non-empty string, or an array of 1 to 2048 non-empty strings.
`encoding_format`	string	No	`float` (an array of numbers) or `base64` (the float32 bytes as a base64 string, which is smaller on the wire). When omitted you get floats.
`dimensions`	integer	No	Return a shorter vector. Only for models that support shortened embeddings, such as the OpenAI `text-embedding-3` models. Leave it out for other models.
`user`	string	No	Accepted for OpenAI SDK compatibility and ignored.

Any other parameter you send is passed to the model provider unchanged, so provider-specific options work without waiting for Gloo to add them. Input rules:

Each string must fit within the model’s input limit (max_input_tokens in the catalog, which is as low as 512 tokens for some models). A longer string is rejected with a 400, so split long documents into chunks first; Building a Knowledge Base covers how.
Arrays of token IDs, which the OpenAI API also accepts, are not supported. Send text.
Empty or whitespace-only strings are rejected.

Response format

{
  "object": "list",
  "data": [
    { "object": "embedding", "index": 0, "embedding": [0.4155, 0.7861, -0.2673, 0.3721, ...] },
    { "object": "embedding", "index": 1, "embedding": [-0.0755, -0.3010, -0.6606, 0.6841, ...] }
  ],
  "model": "gloo-openai-text-embedding-3-small",
  "usage": { "prompt_tokens": 11, "total_tokens": 11 }
}

data holds one embedding per input string, in the same order as input. index is the string’s position.
embedding is the provider’s vector passed through untouched, in the encoding you asked for: an array of floats by default, or a base64 string of little-endian float32 bytes with encoding_format: "base64". Gloo never rounds or converts it.
model is the value you sent.
usage is the number of tokens you are billed for.

Choosing a model

Every model whose output_modalities includes embeddings works here, and sending a chat model returns a 400 that says so. Supported Models lists embedding models alongside chat models, with each model’s input price and its input limit in the Context column. To list only the embedding models, filter the public catalog:

curl -s 'https://platform.ai.gloo.com/platform/v2/models' \
  | jq -r '.data[] | select(.output_modalities | index("embeddings")) | .id'

Two things to settle before you embed a large corpus:

Stay on one model. Vectors from different models, or from the same model with different dimensions, are not comparable. Embed your documents and your queries with the same model and settings, and re-embed everything if you switch.
Vector size differs by model. For example, gloo-openai-text-embedding-3-small returns 1536 numbers and gloo-baai-bge-base-en-v1.5 returns 768. Size your vector store’s column to the model you pick.

What runs, and what doesn’t

This is a direct endpoint. Authentication, organization entitlement, usage metering and platform rate limits apply as everywhere else. Guardrails, moderation, routing and streaming do not: your text goes to the model you name and nothing screens it first. Unlike the direct chat endpoints, embeddings requests are not failed over to a second provider. If the provider is down or rate-limiting, you get a 503 with retryable: true; retry with exponential backoff.

Pricing

Embeddings are billed per input token at the model’s published input rate. There is no output charge and no platform fee. Live rates are on Supported Models and GET /platform/v2/models; your spend shows up in API usage.

Errors

Status	When	Retry?
`400`	The model isn’t an embedding model; `input` is empty, too long, has more than 2048 strings, or contains non-strings; `encoding_format` isn’t `float` or `base64`; or the provider rejected the request. `detail.param` names the field when Gloo caught it.	No. Fix the request.
`402` / `429`	Your organization is out of credit or has reached its spending limit.	Not until the limit is resolved. See Limits.
`422`	A field has the wrong type, such as a non-integer `dimensions`.	No. Fix the request.
`503`	The embedding provider is unavailable or rate-limited.	Yes, with backoff.

The full list of error codes is in Error Reference.

Embeddings API reference: interactive request builder
Supported Models: model IDs, input limits and live pricing
Building a Knowledge Base: chunking documents before you embed them
Endpoint Types: what direct endpoints do and don’t run

Get Started

Responses & Completions

Content

Organization & Billing

Gloo Code

Learn More

External

Legacy

Embeddings

Quick start

With the OpenAI SDK

Request format

Response format

Choosing a model

What runs, and what doesn’t

Pricing

Errors

​Quick start

​With the OpenAI SDK

​Request format

​Response format

​Choosing a model

​What runs, and what doesn’t

​Pricing

​Errors

​Related Documentation

Quick start

With the OpenAI SDK

Request format

Response format

Choosing a model

What runs, and what doesn’t

Pricing

Errors

Related Documentation