Embeddings endpoint

POST /v1/embeddings
Content-Type: application/json
Authorization: Bearer <OLYX_SERVER_API_KEY>

Available through olyx serve, or loopback-only serve --local for experimentation and CI. Application authentication, body-size limits, and the concurrency pool are shared with Chat Completions.

Request

Field	Type	Behavior
model	String, required	Configured alias for an embedding model
input	String, string array, token-ID array, or array of token-ID arrays	Required, nonempty; batches cannot mix input types
encoding_format	float or base64	Defaults to float; base64 encodes little-endian float32 vectors
dimensions	Positive integer	Optional; provider/model must support the requested width
user	String	Optional provider end-user identifier

Other provider-specific fields are forwarded to compatible providers for validation. stream, messages, and native_request are rejected. Chat output-token controls are not injected into embedding requests. Token limits are enforced by the selected provider/model; Olyx does not tokenize or truncate document text.

{"model":"embed","input":["Document chunk","Another chunk"],"encoding_format":"float"}

Send a batch through your local server:

curl http://127.0.0.1:8787/v1/embeddings \
  -H "Authorization: Bearer $OLYX_SERVER_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model":"embed","input":["Document chunk","Another chunk"]}'

This assumes an embed alias and a running server. See RAG setup.

Response

{
  "object": "list",
  "model": "text-embedding-3-small",
  "data": [
    {"object": "embedding", "index": 0, "embedding": [0.1, 0.2]},
    {"object": "embedding", "index": 1, "embedding": [0.3, 0.4]}
  ],
  "usage": {"prompt_tokens": 5, "total_tokens": 5}
}

The values above illustrate the response shape. Actual vector width depends on the model and optional dimensions. Entries are ordered by their input index. The model is required in the provider response and must match the configured model or one of its explicit embedding_response_models identifiers. Usage is returned as reported by the provider. Responses include X-Olyx-Trace-Id for local debugging and replay.

Olyx validates the number of vectors, unique indices, finite vector components, consistent dimensions, and any explicitly requested dimensions. It rejects malformed, truncated, or oversized successful responses with HTTP 502.

Providers and fallback

Use an OpenAI-compatible embedding endpoint or a plugin declaring embeddings. Chat compatibility does not establish embedding compatibility.

Fallback candidates must use the same protocol and configured model identifier. Otherwise the request fails with HTTP 400 embedding_fallback_model_mismatch before any provider call. Transport errors, 429, and 5xx try the next configured replica; authentication errors, other provider rejections, and malformed successful responses stop execution. Configure replicas that serve the same model version and vector space, with the same embedding_response_models identifiers on every candidate.

Storage and limits

Requests use policy.max_body_bytes (256 KiB by default). Responses use policy.max_embedding_response_bytes (64 MiB by default, up to 1 GiB). Exceeding the request limit returns 413. Exceeding the response limit returns 502 embedding_response_too_large. Plugins also enforce a 1 MiB limit per JSON event; see the plugin protocol. The concurrency pool returns 429 server_busy when full.

SQLite traces retain input and summary metadata, including count, dimensions, encoding, usage, latency, and cost telemetry. Vector values are only returned to the application. Replay reissues embedding calls and returns summaries; comparisons do not score vector similarity or retrieval quality.

See Embeddings and RAG for a runnable indexing and retrieval example, and Configuration for storage and policy settings.