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 to build semantic search, retrieval-augmented generation (RAG), clustering, deduplication and recommendations on top. New to the idea? Embeddings: How AI Understands Meaning explains it. 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"
  }'

Send your API key as a Bearer token, as on the rest of the platform. 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

Send model (an embedding model’s Gloo Model ID; see Choosing a model) and input (one non-empty string, or an array of 1 to 2048). Optional encoding_format (float or base64) follows OpenAI’s API; if omitted, the provider’s default applies, so set it when your client needs a particular encoding. Optional dimensions shortens the vector, but support varies by model and an unsupported value returns 400; see Dimension support. For every field, see the Embeddings API reference. 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; real vectors contain the model’s full number of dimensions. data holds one embedding per input string, in the same order as input. embedding is the provider’s vector passed through untouched. If a provider does not honor a requested encoding, Gloo returns 503 instead of a response in the wrong shape. usage 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'

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; see Pricing. 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.

Next steps

For model IDs, input limits and live pricing, see Supported Models. For direct generation endpoints, see Direct Responses and Direct Completions. For how documents are split, see How Chunking Works; the tutorial generates its answer with Guarded Responses.

Semantic Search with the Embeddings API

End-to-end tutorial that chunks a corpus, indexes it with this endpoint, ranks chunks by cosine similarity, and generates a cited answer with Guarded Responses.

Building a Knowledge Base

Chunking documents before you embed them.

Embeddings API reference

Interactive request builder.

Start Here

Inference and APIs

Data Engine

Studio

Gloo Code

Learn More

Legacy

Quick start

With the OpenAI SDK

Request format

Response format

Choosing a model

Dimension support

What runs, and what doesn’t

Pricing

Errors

Next steps

Semantic Search with the Embeddings API

Building a Knowledge Base

Embeddings API reference

​Quick start

​With the OpenAI SDK

​Request format

​Response format

​Choosing a model

​Dimension support

​What runs, and what doesn’t

​Pricing

​Errors

​Next steps

Semantic Search with the Embeddings API

Building a Knowledge Base

Embeddings API reference

Quick start

With the OpenAI SDK

Request format

Response format

Choosing a model

Dimension support

What runs, and what doesn’t

Pricing

Errors

Next steps