Skip to Content
API AccessEmbeddings

Embeddings

POST /v1/embeddings
Content-Type: application/json
Authorization: Bearer sk-steinkauz-live-...

The embeddings endpoint follows the common OpenAI Embeddings API  request and response shape. It is useful for clients such as retrieval pipelines and n8n flows when your configured provider exposes an embedding model.

curl -sS "$STEINKAUZ_BASE_URL/v1/embeddings" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $STEINKAUZ_API_KEY" \
  -d '{
    "model": "vercel-ai-gateway/openai/text-embedding-3-small",
    "input": ["First document", "Second document"]
  }'

Supported fields are:

  • model
  • input as one non-empty string or an array of non-empty strings
  • dimensions when the upstream model/provider supports it
  • encoding_format as float (default) or base64
  • user

Token-ID arrays are not accepted because their tokenization is provider-specific.

For local services such as TEI, configure an OpenAI Compatible connection. Clients prepare query/document text and manage model revision, dimensions, normalization and preprocessing. Validate returned vectors and explicitly migrate indexes when their embedding space changes.

Media embeddings

An OpenAI Compatible server that implements the vLLM messages embeddings extension  can receive messages instead of input. One user conversation produces one embedding:

{
  "model": "connection/CONNECTION_UUID/google/embeddinggemma-2",
  "add_special_tokens": true,
  "messages": [{
    "role": "user",
    "content": [{
      "type": "image_url",
      "image_url": { "url": "data:image/png;base64,BASE64_BYTES" }
    }]
  }]
}

The supported parts are prepared text, inline image_url (PNG, JPEG, WebP), input_audio with base64 data and format (wav or mp3), and inline video_url (MP4). Only one user message with 1–32 parts is accepted. Decoded media and text together must fit 32 MiB, and the JSON request must fit 48 MiB. Remote URLs and arbitrary client provider options are rejected. The selected server must support the requested model and media. Inputs exceeding its context limit fail; prepare and segment content before sending it.

Dimensions are optional and depend on server support. Stock vLLM 0.32.0 rejects a dimensions field for EmbeddingGemma 2, including 768. Request its native output and validate that each vector has 768 finite, nonzero coordinates. A failed dimensions request is not automatically retried with a different body.

The messages extension accepts the optional vLLM add_special_tokens boolean. The qualified EmbeddingGemma 2 recipe sets it to true so that messages include the BOS/EOS tokens used by standard text input. This is a client preprocessing choice; omission preserves the server’s defaults. Changing it requires checking the application’s embedding-space identity and migration rules.

The AI SDK OpenAI-compatible embedding adapter accepts string values and drops arbitrary embedding options. For media, use its documented custom fetch hook to replace its single placeholder input with validated messages. Guard against multiple SDK values, since one conversation produces one joint vector. Do not assume providerOptions passthrough. Standard text embed/embedMany calls continue to work unchanged.

google/embeddinggemma-2 is distinct from google/gemini-embedding-2 and google/embeddinggemma-300m. Stock TEI support for the older text model does not establish support for EmbeddingGemma 2. Use a serving engine with verified architecture and media support. Clients preserve their local weights/preprocessing identity and explicitly migrate indexes when sampling or preprocessing changes. Concrete requests do not require a Steinkauz profile or embedding-space header.

Model discovery

Model listings and capability information are advisory. A listed model may not support embeddings, and an unlisted model can still be selected manually. The selected provider returns an error if the model cannot perform the requested operation.

Embedding requests are supported on Vercel AI Gateway, OpenAI, Azure OpenAI, OpenAI Compatible, Google Generative AI, Google Vertex AI, and Mistral connections, subject to model support. Anthropic connections do not support this endpoint.

Embedding requests use the same API-key authentication, D×E routing policy and Budgets as other inference requests. Reported usage and cost appear in Activity.

ResponsesTimed speech transcription