Skip to main content

Embeddings API

Generate dense vector embeddings across OpenAI, Google Gemini, Mistral, Cohere Embed v3, and Voyage AI using a single unified schema. Vector embeddings transform text into high-dimensional numerical vectors for semantic search, retrieval-augmented generation (RAG), clustering, and classification.


Endpoint Specification​

  • Method: POST
  • Path: /v1/embeddings (also supports unversioned /embeddings)
  • Authentication: Bearer sk-gw-... (Virtual Key or Master Admin Key)
  • Content-Type: application/json

Supported Providers & Model Families​

GoRoute standardizes embedding generation across leading model providers:

ProviderNotable ModelsDimensionsFeatures
OpenAItext-embedding-3-small, text-embedding-3-large1536 / 3072Matryoshka dimension truncation, float & base64.
Coherecohere/embed-english-v3.0, cohere/embed-multilingual-v3.01024Task-specific optimization (search_document, search_query).
Voyage AIvoyage/voyage-3, voyage/voyage-3-large, voyage/voyage-code-31024 / 1536Optimized for code search, legal, and enterprise RAG.
Googlegemini/text-embedding-004768High-throughput low-latency multilingual embeddings.
Mistralmistral/mistral-embed1024European data locality and multi-language support.

Request & Response Schemas​

Request Schema (CanonicalEmbeddingRequest)​

{
"model": "text-embedding-3-small",
"input": [
"GoRoute AI Gateway provides sub-millisecond routing.",
"Pure Go compiles to native machine code without Cgo."
],
"encoding_format": "float",
"dimensions": 512
}
FieldTypeRequiredDescription
modelstringYesModel identifier or provider alias (e.g. text-embedding-3-small, voyage/voyage-3).
inputstring | string[]YesInput text or array of input texts to vectorize.
encoding_formatstringNofloat (default) or base64. Base64 yields smaller HTTP payload sizes.
dimensionsintegerNoTruncate dimensions on models supporting Matryoshka embeddings (e.g. OpenAI v3).
userstringNoOptional end-user identifier for abuse monitoring.

Response Schema (CanonicalEmbeddingResponse)​

{
"object": "list",
"data": [
{
"object": "embedding",
"index": 0,
"embedding": [0.0123, -0.0456, 0.0789, "..."]
}
],
"model": "text-embedding-3-small",
"usage": {
"prompt_tokens": 16,
"total_tokens": 16
}
}

[!NOTE] When encoding_format: "base64" is requested, each item's embedding contains a base64-encoded string representing the Little-Endian IEEE 754 binary floating-point array, dramatically shrinking response payload size over HTTP.


Code Examples​

# 1. OpenAI Embeddings with Matryoshka dimension reduction
curl -X POST http://localhost:8080/v1/embeddings \
-H "Authorization: Bearer sk-gw-prod-7f9a2b8c4d1e" \
-H "Content-Type: application/json" \
-d '{
"model": "text-embedding-3-small",
"input": [
"GoRoute AI Gateway provides sub-millisecond routing.",
"Pure Go compiles to native machine code without Cgo."
],
"dimensions": 512
}'

# 2. Voyage AI Code Embeddings
curl -X POST http://localhost:8080/v1/embeddings \
-H "Authorization: Bearer sk-gw-prod-7f9a2b8c4d1e" \
-H "Content-Type: application/json" \
-d '{
"model": "voyage/voyage-code-3",
"input": "func ServeHTTP(w http.ResponseWriter, r *http.Request)"
}'

# 3. Cohere Embed v3
curl -X POST http://localhost:8080/v1/embeddings \
-H "Authorization: Bearer sk-gw-prod-7f9a2b8c4d1e" \
-H "Content-Type: application/json" \
-d '{
"model": "cohere/embed-english-v3.0",
"input": ["Document text to index in vector database"]
}'

Response Telemetry & FinOps Ledger​

Every embeddings request returns:

  • X-Gateway-Request-Id: Unique request UUID (req_...)
  • X-Gateway-Provider: Provider used (openai, voyage, cohere)
  • X-Gateway-Cost-Micros: Exact micro-dollar cost based on input tokens
  • X-Gateway-Pricing-Status: verified, custom, or unknown

[!TIP] Use POST /v1/tokenize to pre-calculate embedding batch sizes and stay within upstream token limits without running extra network calls.