Embeddings

POST /v1/embeddings is an OpenAI-compatible endpoint that turns text into dense vectors. The gateway selects the provider for the requested embedding model and returns the vectors in the standard data[].embedding field. An embedding is a numerical representation of meaning: text with similar meaning tends to be close in vector space. Applications commonly store these vectors in a vector database and use them for semantic search, retrieval- augmented generation, recommendations, clustering, or classification.

Quick start

curl -X POST "https://api.llmapi.ai/v1/embeddings" \
  -H "Authorization: Bearer $LLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-3-small",
    "input": ["A short document", "A second document"]
  }'

The response contains one vector per input item. Store vectors produced by the same model together; embeddings from different models can have different dimensions and vector spaces.

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.0123, -0.0456, 0.0789]
    },
    {
      "object": "embedding",
      "index": 1,
      "embedding": [0.0234, -0.0567, 0.089]
    }
  ],
  "model": "text-embedding-3-small",
  "usage": { "prompt_tokens": 8, "total_tokens": 8 }
}

The real vector contains many more dimensions than the abbreviated example. Use data[index] to associate each vector with the corresponding input item.

Request fields

Field	Required	Description
`model`	Yes	Embedding model ID. Check the model catalog for dimensions, limits, and provider availability.
`input`	Yes	One string or an array of strings. Array items are returned in the same order.
`encoding_format`	No	`float` returns a JSON number array. `base64` is supported only by providers that advertise it.
`dimensions`	No	Requested output dimensions when supported by the model.
`user`	No	Opaque end-user identifier for attribution.

For a document search system, embed documents at ingestion time and embed the user query at search time with the same model:

curl -X POST "https://api.llmapi.ai/v1/embeddings" \
  -H "Authorization: Bearer $LLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-3-small",
    "input": "How do I rotate an API key?",
    "encoding_format": "float"
  }'

Compare vectors with the metric expected by your database, usually cosine similarity or dot product. Do not mix vectors from different models or change dimensions after creating an index without re-embedding the stored data.

Notes

encoding_format: "base64" is not available for Jina or Mistral models; use float for those providers.
Embeddings are synchronous and do not support streaming or output guardrails. Large ingestion jobs should be chunked into provider-supported input batches and retried with backoff.
The gateway can fan out or batch provider calls for array input, but the request remains one synchronous HTTP operation.
Input guardrails can reject or mask content before forwarding. Response caching can avoid repeated provider calls when enabled; see Response caching and Guardrails.
A request can fail for an unknown model, oversized input, unsupported dimensions or encoding, insufficient credits, or a provider error. Check the model catalog before deploying a fixed model ID.