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."],
    "encoding_format": "float"
  }'

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."],
    encoding_format="float",
)

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.'],
  encoding_format: 'float',
});

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` (little-endian float32 bytes as a base64 string). When omitted, the provider’s default applies. Set this explicitly when your client requires a particular encoding.
`dimensions`	integer	No	Request a vector width. Support and accepted values vary by model; unsupported models or values return `400`. See Dimension support.
`user`	string	No	Accepted for OpenAI SDK compatibility and ignored.

Provider-specific parameters are forwarded to the model provider unless Gloo reserves or rejects them. stream and provider are not forwarded. The aliases dimension, output_dimension, and output_dimensionality return 400; use dimensions instead. 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 }
}

The vectors above are shortened for readability; real vectors contain the model’s full number of dimensions.

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. It is an array when the provider returns floats, or a base64 string when the provider honors encoding_format: "base64". If you omit encoding_format, the provider chooses its default. If a provider does not honor a requested encoding, Gloo returns 503 instead of a response in the wrong shape.
model is the value you sent.
usage reports the provider’s token counts and may be omitted when the provider does not report usable usage. Requests without usage are not billed.

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 identifies embedding models and lists each model’s input price, vector width, and input limit. To list only 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.

Dimension support

Only some embedding models accept dimensions. For example, the OpenAI text-embedding-3 models accept widths up to their native size, Perplexity models require at least 128, and Voyage models accept 256, 512, 1024, or 2048. Other models reject this parameter with 400. The public model catalog reports native vector width, but does not currently list which shortened widths a model accepts. A 400 response identifies the accepted values or range when available.

What runs, and what doesn’t

This is a direct endpoint. Authentication, organization entitlement, usage metering, and platform rate limits apply. Guardrails and moderation do not run, and embeddings do not use automatic model routing or streaming. Your text goes to the embedding model you name. Embeddings requests are not failed over to a second provider. A provider outage or rate limit returns 503 with retryable: true; retry with bounded exponential backoff. Gloo also returns 503 if the provider returns an empty, incomplete, unusable, or incorrectly encoded vector batch. If the same request repeatedly fails because the provider does not support a requested encoding, change the request or model instead of retrying unchanged.

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` is invalid; `dimensions` is unsupported or out of range; a dimension alias was used; or the provider rejected the request. Gloo validation errors include `detail.param` when applicable.	No. Fix the request.
`401` / `403`	Authentication failed or the organization is not permitted to use the API.	No. Check the API key and organization access.
`402` / `429`	Your organization is out of credit or has reached its spending limit.	Not until the limit is resolved. See Limits.
`422`	The request body has a field with the wrong type, such as a non-integer `dimensions`.	No. Fix the request.
`503`	The provider is unavailable or rate-limited, or returned vectors that are empty, incomplete, unusable, or in a different encoding than requested.	Retry transient provider failures with backoff. Change the request or model if the failure persists for the same input and options.

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
Direct Responses and Direct Completions: direct generation endpoints

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

Dimension support

What runs, and what doesn’t

Pricing

Errors

​Quick start

​With the OpenAI SDK

​Request format

​Response format

​Choosing a model

​Dimension support

​What runs, and what doesn’t

​Pricing

​Errors

​Related Documentation

Quick start

With the OpenAI SDK

Request format

Response format

Choosing a model

Dimension support

What runs, and what doesn’t

Pricing

Errors

Related Documentation