Embeddings¶
Embedding calls often carry whole documents: your knowledge base, chunk by chunk, on its way to a provider. Through the gateway, they're checked against your policies, charged to the right team and recorded, with no change to your code beyond the two settings.
What it is¶
POST /v1/embeddings, OpenAI's endpoint that turns text into vectors. The gateway passes it on unchanged to a
provider that speaks the OpenAI API: OpenAI, Azure OpenAI, and providers added with the OpenAI kind of API that
offer embeddings (Mistral, Together AI and others). It isn't translated: embedding APIs differ too much between
providers, and Anthropic has no embedding models. A call to a Claude or Gemini model gets a 400.
The two settings¶
The same as for the OpenAI SDK: base address https://<your-gateway>/v1 and your Vidai key. See
OpenAI SDK for Python.
A minimal call¶
from openai import OpenAI
client = OpenAI() # reads OPENAI_BASE_URL and OPENAI_API_KEY
result = client.embeddings.create(
model="text-embedding-3-small",
input=["Zuiderhoeve Dairy brand guide", "Fjordair route map"],
)
print(len(result.data), len(result.data[0].embedding))
import OpenAI from "openai";
const client = new OpenAI();
const result = await client.embeddings.create({
model: "text-embedding-3-small",
input: ["Zuiderhoeve Dairy brand guide", "Fjordair route map"],
});
console.log(result.data.length, result.data[0].embedding.length);
curl https://<your-gateway>/v1/embeddings \
-H "Authorization: Bearer $OPENAI_API_KEY" -H "Content-Type: application/json" \
-d '{"model": "text-embedding-3-small", "input": "Zuiderhoeve Dairy brand guide"}'
The model name is an example: use one your organisation approved under Models.
Reading what the gateway did¶
Use client.embeddings.with_raw_response.create(...) (Python) or .withResponse() (TypeScript) and read
x-vidai-request-id and x-vidai-model, as shown on Chat Completions.
The tokens and the cost are in Request logs.
Errors¶
The codes are those of Chat Completions. Specific to this endpoint: a model on a provider that doesn't speak the OpenAI API (Claude, Gemini, Bedrock) gets a 400, and nothing is sent.
What goes through the gateway¶
| Feature | Through the gateway |
|---|---|
embeddings.create, one text or a list |
Yes, to OpenAI-format providers |
| Gemini embeddings | Through the Gemini format instead (:embedContent), see Gemini generateContent |
| Claude, Bedrock | No embeddings here: a 400 |
Check it works in a minute¶
Run the curl above. An answer with a data list means the address, key and model are right.
Good to know¶
- Guardrails: your own patterns apply to the text. A VidaiGuard check set to mask or pseudonymise only records what it found here (the call goes through unchanged), and a pattern set to pseudonymise refuses the call: use mask instead if these calls should go through.
- The SDK may send
encoding_format: "base64"and decode it for you; that passes through unchanged.