Embeddings

Endpoint

POST https://api.bve.me/v1/embeddings

Requires Authorization: Bearer sk-bve-YOUR_KEY.

This endpoint proxies directly to Fuelix /embeddings. The request body and response shape follow the OpenAI Embeddings API.

Request body

{
  "model": "text-embedding-3-small",
  "input": "The quick brown fox"
}

Field	Type	Required	Description
model	string	Yes	Embedding model ID
input	string | array	Yes	Text to embed — string or array of strings
encoding_format	string	No	float or base64 (default: float)
dimensions	integer	No	Output dimensions; only supported by OpenAI text-embedding-3-* models
input_type	string	No	Cohere embed model task type — "search_query", "search_document", "classification", or "clustering". Required by Cohere embed-*-v3 models; silently ignored by other providers.
truncate	string	No	Groq overflow behaviour — "NONE" (error on overflow), "START" (trim from start), or "END" (trim from end, default). Case-sensitive. Silently ignored by non-Groq providers.
user	string	No	End-user identifier (≤ 256 chars)

Response

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.0023, -0.0089, 0.0141, "..."]
    }
  ],
  "model": "text-embedding-3-small",
  "usage": {
    "prompt_tokens": 6,
    "total_tokens": 6
  }
}

Examples

Single input

TypeScript

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-bve-YOUR_KEY',
  baseURL: 'https://api.bve.me/v1',
});

const response = await client.embeddings.create({
  model: 'text-embedding-3-small',
  input: 'The quick brown fox',
});

console.log(response.data[0].embedding);

Python

from openai import OpenAI

client = OpenAI(
    api_key="sk-bve-YOUR_KEY",
    base_url="https://api.bve.me/v1",
)

response = client.embeddings.create(
    model="text-embedding-3-small",
    input="The quick brown fox",
)

print(response.data[0].embedding)

cURL

curl https://api.bve.me/v1/embeddings \
  -H "Authorization: Bearer sk-bve-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-3-small",
    "input": "The quick brown fox"
  }'

Batch embedding (multiple inputs)

Pass an array of strings to embed multiple texts in a single request:

TypeScript

const response = await client.embeddings.create({
  model: 'text-embedding-3-small',
  input: ['The quick brown fox', 'jumped over', 'the lazy dog'],
});

for (const item of response.data) {
  console.log(`index=${item.index}, vector_length=${item.embedding.length}`);
}

Python

response = client.embeddings.create(
    model="text-embedding-3-small",
    input=["The quick brown fox", "jumped over", "the lazy dog"],
)

for item in response.data:
    print(f"index={item.index}, vector_length={len(item.embedding)}")

cURL

curl https://api.bve.me/v1/embeddings \
  -H "Authorization: Bearer sk-bve-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-3-small",
    "input": ["The quick brown fox", "jumped over", "the lazy dog"]
  }'

Embedding-only models

Embedding models (text-embedding-3-small, text-embedding-3-large, text-embedding-ada-002, gemini-embedding-001) can only be used with /v1/embeddings. Sending an embedding model to /v1/chat/completions or any other endpoint returns 400 model_endpoint_mismatch before the request reaches Fuelix. See Endpoint compatibility.

Response headers

BVE Gateway adds the following headers to every authenticated response:

Header	Example	Description
X-Request-Id	550e8400-…	UUID for this request (generated per request)
X-BVE-Client-Id	my-trace-123	Echo of the client-supplied X-Request-Id (when present and valid: alphanumeric + -_., ≤ 128 chars). Absent when not supplied or value failed validation.
X-BVE-Latency	143	Total gateway latency in milliseconds
X-BVE-Model	text-embedding-3-small	Model ID resolved for this request
X-BVE-Key-Name	prod-key	Name of the API key used for this request (redacted if it matches a provider credential pattern)

The full X-RateLimit-* header set (RPM, RPD, monthly) is also included. See Rate Limits & Quotas for details and example output.

Gateway validation

The gateway validates required and optional fields before forwarding to Fuelix. Invalid inputs return 400 with an OpenAI-compatible error body instead of a Fuelix Pydantic error.

Required fields:

Missing / invalid	Code	param
model absent	missing_required_parameter	"model"
model not a string	invalid_type	"model"
input absent	missing_required_parameter	"input"
input not a string or array	invalid_type	"input"

Optional field constraints:

Field	Constraint	Code	param
encoding_format	Not a string	invalid_type	"encoding_format"
encoding_format	Not "float" or "base64"	invalid_value	"encoding_format"
dimensions	Not a number	invalid_type	"dimensions"
dimensions	Not a positive integer	invalid_value	"dimensions"
input_type	Not a string	invalid_type	"input_type"
input_type	Not one of "search_query", "search_document", "classification", "clustering"	invalid_value	"input_type"
truncate	Not a string	invalid_type	"truncate"
truncate	Not one of "NONE", "START", "END" (case-sensitive)	invalid_value	"truncate"
user	Not a string	invalid_type	"user"
user	More than 256 characters	invalid_value	"user"

Provider-specific parameters

Cohere — input_type

Cohere v3 embed models (embed-english-v3.0, embed-multilingual-v3.0, and dated variants) require an input_type hint to optimise the embedding for its intended use:

Value	Use case
"search_query"	Embed a user’s search query for retrieval against indexed documents
"search_document"	Embed a passage to be stored in a retrieval index
"classification"	Embed text for classification tasks
"clustering"	Embed text for clustering or similarity tasks

curl https://api.bve.me/v1/embeddings \
  -H "Authorization: Bearer sk-bve-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "embed-english-v3.0",
    "input": "What is the capital of France?",
    "input_type": "search_query"
  }'

Other providers (OpenAI, Groq) ignore input_type silently.

Groq — truncate

Groq embedding models (nomic-embed-text-v1.5 and similar) accept a truncate parameter that controls behaviour when the input exceeds the model’s context window:

Value	Behaviour
"END"	Remove tokens from the end of the input (Groq default)
"START"	Remove tokens from the beginning of the input
"NONE"	Return an error if the input is too long

Values are case-sensitive — "end" or "End" are rejected with 400 invalid_value.

curl https://api.bve.me/v1/embeddings \
  -H "Authorization: Bearer sk-bve-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nomic-embed-text-v1.5",
    "input": "...(long document)...",
    "truncate": "END"
  }'

Next steps

Models Full embedding model catalog — text-embedding-3-small, text-embedding-3-large, and more

Rate Limits & Quotas Per-key RPM/RPD limits, monthly caps, and Retry-After handling

Errors Full error code reference including model_endpoint_mismatch for embedding models