API

Dzen Embedder exposes one embedding method: POST /v1/embeddings. It converts text into numerical vectors for search, similarity, and RAG. The examples assume a running local server with the default model deepvk/USER-bge-m3.

Create embeddings

POST http://127.0.0.1:8091/v1/embeddings
Content-Type: application/json

Request body

Field	Type	Required	Description
model	string	Yes	Must exactly match the server's model_id. The default is deepvk/USER-bge-m3.
input	string or non-empty array of strings	Yes	One text or several texts to embed. Token-ID arrays are not supported.
encoding_format	string	No	Only float is supported; the server defaults to it. Set it explicitly when using the OpenAI Python library.

Optional header X-Dzen-Embedding-Priority: batch sends work to the background queue. Without it, requests use the realtime queue. Both return the same synchronous response; this is not OpenAI's Batch API. Priority affects queue scheduling and does not interrupt inference already in progress.

Embedder has no built-in API-key validation. The local examples need no credentials. For a deployment behind an authenticated proxy, use its URL and credentials. See network access.

Response

A successful request returns HTTP 200 and JSON:

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.012, -0.034, 0.056]
    }
  ],
  "model": "deepvk/USER-bge-m3",
  "usage": {"prompt_tokens": 0, "total_tokens": 0}
}

The vector above is illustrative, shortened to three values. Real vector length depends on the loaded model. Each data item corresponds to an input, with a zero-based index. The usage fields are placeholders, not measured token counts.

curl

Embed one text (Bash on Linux, macOS, or WSL):

curl --fail-with-body --max-time 60 \
  http://127.0.0.1:8091/v1/embeddings \
  -H 'Content-Type: application/json' \
  -d '{"model":"deepvk/USER-bge-m3","input":"How do I add document search?","encoding_format":"float"}'

Embed several document chunks with background priority:

curl --fail-with-body --max-time 60 \
  http://127.0.0.1:8091/v1/embeddings \
  -H 'Content-Type: application/json' \
  -H 'X-Dzen-Embedding-Priority: batch' \
  -d '{"model":"deepvk/USER-bge-m3","input":["First document chunk","Second document chunk"],"encoding_format":"float"}'

Python with the standard library

No additional packages are required. urlopen raises HTTPError for unsuccessful HTTP responses.

import json
from urllib.request import Request, urlopen

texts = ["First document chunk", "Second document chunk"]
request = Request(
    "http://127.0.0.1:8091/v1/embeddings",
    data=json.dumps({
        "model": "deepvk/USER-bge-m3",
        "input": texts,
        "encoding_format": "float",
    }).encode("utf-8"),
    headers={"Content-Type": "application/json"},
    method="POST",
)
with urlopen(request, timeout=60) as response:
    result = json.load(response)

for item in result["data"]:
    vector = item["embedding"]
    print(texts[item["index"]], len(vector), vector[:5])

OpenAI Python library

Install the client in your Python environment:

python -m pip install openai

Use a custom base_url ending in /v1, not /v1/embeddings. The client requires an api_key; the placeholder below is only for the local server, which does not validate it.

from openai import OpenAI

with OpenAI(
    base_url="http://127.0.0.1:8091/v1",
    api_key="local-not-used",
    timeout=60.0,
    max_retries=0,
) as client:
    response = client.embeddings.create(
        model="deepvk/USER-bge-m3",
        input=["First document chunk", "Second document chunk"],
        encoding_format="float",
    )
    for item in response.data:
        print(item.index, len(item.embedding), item.embedding[:5])

For background indexing, add extra_headers={"X-Dzen-Embedding-Priority": "batch"} to client.embeddings.create(...). Automatic retries are disabled in this example so a timeout does not silently repeat inference work.

Always pass encoding_format="float": the OpenAI Python client's embeddings implementation can request base64 when this parameter is omitted, which Embedder does not support.

Errors and compatibility

HTTP status	Meaning	What to check
400	Invalid request	JSON body must be an object; check model ID, text inputs, and encoding_format.
503	Service unavailable	Read the response body and inspect service logs and queue state.
504	Embedding request timed out	Reduce request size or load; check request_timeout_seconds (default: 30 seconds).

Validation and service errors may have plain-text bodies rather than OpenAI-style JSON errors. A longer client timeout does not extend the server's timeout.

This endpoint supports the embeddings request and response shape described above, not every OpenAI API feature. It does not implement dimensions, base64 output, token-ID input, model listing, or chat completions. Do not rely on additional request fields changing the result.

When switching embedding models, re-embed existing documents and use the same new model for queries. Matching vector dimensions alone does not make vectors from different models compatible.

See the request handler for the implementation and First request and configuration for readiness checks and deployment settings.