POST/v1/embeddings

Embeddings

Create a vector embedding for input text.

OpenAI-dialect embeddings. Typically served by on-cluster open-weight models (e.g. bge-m3).

Request body

Field	Type	Required	Notes
`model`	string	yes	An embedding alias (e.g. `bge-m3`).
`input`	string \| string[] \| number[][]	yes	Text (or token arrays) to embed.
`encoding_format`	`float` \| `base64`	no	`base64` returns the vector base64-encoded.
`dimensions`	integer	no	Forwarded to the provider (model-dependent).
`user`	string	no	Forwarded to the provider unchanged.

Code sample

curl https://api.<domain>/v1/embeddings \
  -H "Authorization: Bearer $TOKENFACTORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bge-m3",
    "input": "The quick brown fox"
  }'

from openai import OpenAI

client = OpenAI(
    base_url="https://api.<domain>/v1",
    api_key=os.environ["TOKENFACTORY_API_KEY"],
)

response = client.embeddings.create(
    model="bge-m3",
    input="The quick brown fox",
)
print(response.data[0].embedding[:5])

Response

{
  "object": "list",
  "data": [
    { "object": "embedding", "index": 0, "embedding": [0.1, 0.2, "…"] }
  ],
  "model": "bge-m3",
  "usage": { "prompt_tokens": 4, "total_tokens": 4, "prompt_tokens_details": { "cached_tokens": 0, "cache_write_tokens": 0 } },
  "provider_metadata": { "provider": "vllm-staging", "actual_model": "BAAI/bge-m3" }
}

Guaranteed fields: object: "list", data[].{object, index, embedding}, model (your alias), usage{prompt_tokens, total_tokens}, and provider_metadata.

usage.prompt_tokens_details.{cached_tokens,cache_write_tokens} are always present, defaulting to 0 when the backend didn't report caching — the gateway normalizes this shape the same way it does for Chat Completions, so an embeddings backend that omits the field (or sends it as null) never produces a different observable shape than one that reports real cache numbers.

Errors

Standard error surface — see Errors.