> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Embeddings
> POST /ai/v2/direct/embeddings — turn text into embedding vectors with any Gloo embedding model, using the OpenAI-compatible Embeddings request shape.
**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](/ai-learning-center/gloo-ai-103/embeddings) 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](/api-guides/search) and the [grounded endpoints](/api-guides/endpoint-types#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`
```bash theme={null}
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](/studio/manage-api-credentials).
### With the OpenAI SDK
```python Python theme={null}
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))
```
```typescript TypeScript theme={null}
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](#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](/ai-learning-center/gloo-ai-103/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
```json theme={null}
{
"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](/api-guides/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:
```bash theme={null}
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](/api-guides/endpoint-types#direct-endpoints). 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](/api-guides/supported-models) and `GET /platform/v2/models`; your spend shows up in [API usage](/studio/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](/api-reference/general/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](/api-reference/general/errors).
## Related Documentation
* [Embeddings API reference](/api-reference/embeddings/direct): interactive request builder
* [Supported Models](/api-guides/supported-models): model IDs, input limits and live pricing
* [Building a Knowledge Base](/ai-learning-center/gloo-ai-103/building-a-knowledge-base): chunking documents before you embed them
* [Endpoint Types](/api-guides/endpoint-types): what direct endpoints do and don't run