Develop / Reference

Embeddings

Generates vector embeddings in the OpenAI format and inspects the input with Noirdoc Shield before forwarding when Shield is active.

POST /v1/embeddings
Family
embeddings
Shield
yes
Streaming
no
Format
JSON
Billing
tokens (input)

Request

The gateway accepts the body in the format of the OpenAI Embeddings API. model is required and must be a model of the embeddings family from GET /v1/models. The gateway answers a chat model on this endpoint with 400 wrong_endpoint_for_model, and likewise an embedding model on a chat endpoint.

When Noirdoc Shield is active (default_on, enforced, key or request-tag shield_mode: on, or the X-Noirdoc-Shield: on header), Shield inspects and redacts input before forwarding it to the provider (see Set up Noirdoc Shield).

The gateway forwards further fields such as encoding_format or dimensions to the provider. The provider decides whether the model supports them.

Shell
curl https://api.noirdoc.de/v1/embeddings \
  -H "Authorization: Bearer $NOIRDOC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "BAAI/bge-m3",
    "input": [
      "The notice period is three months.",
      "The contract ends at the end of the quarter."
    ]
  }'
Python
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.noirdoc.de/v1",
    api_key=os.environ["NOIRDOC_API_KEY"],
)

response = client.embeddings.create(
    model="BAAI/bge-m3",
    input=[
        "The notice period is three months.",
        "The contract ends at the end of the quarter.",
    ],
)
print(len(response.data[0].embedding))
TypeScript
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.noirdoc.de/v1",
  apiKey: process.env.NOIRDOC_API_KEY,
});

const input: string[] = [
  "The notice period is three months.",
  "The contract ends at the end of the quarter.",
];

const response = await client.embeddings.create({
  model: "BAAI/bge-m3",
  input,
});
console.log(response.data[0].embedding.length);

What Noirdoc changes

AreaBehaviour
ModelThe gateway resolves the model ID through the catalogue and sends the provider its own model name. If the response’s model field contains this name, the gateway replaces it with the ID you sent.
ProviderThe X-Noirdoc-Provider header in the response names the provider. See Providers & routing.
Noirdoc ShieldWhen Shield is active (default_on, enforced, key or request-tag shield_mode: on, or X-Noirdoc-Shield: on), Shield inspects string inputs, string arrays, multimodal text fields and even integer token arrays (decoded via tiktoken, redacted and re-encoded into token IDs) before forwarding. The response carries X-Noirdoc-Shield: redacted=<n> and X-Noirdoc-Masked: true; on a block match, the gateway rejects the request with 403 shield_violation (see Inspected fields).
StreamingNone. The gateway answers "stream": true with 400 streaming_not_supported_for_endpoint.
BillingThe gateway bills the input tokens from usage (plus Noirdoc Shield when inspection is active, see Billing). If the provider reports no usage, it estimates the input tokens from the body.
HeadersThe gateway removes your key, X-Noirdoc-Shield and X-Noirdoc-Mask before forwarding the request.

Only pre-existing organisations still on legacy masking until 30.11.2026 receive 403 masking_not_supported_for_endpoint on /v1/embeddings under enforced or X-Noirdoc-Mask: on — unless they opt into Noirdoc Shield via X-Noirdoc-Shield: on or by switching under Models → Shield.

Sub-routes

None. The gateway answers other paths under /v1/embeddings/ with 404 unsupported_endpoint.

Errors on this endpoint

Status Code Meaning
400 model_required The request names no model (model in the body, or in the form field for /v1/audio/transcriptions).
400 wrong_endpoint_for_model The model belongs to a different endpoint family or API format than the endpoint called.
400 streaming_not_supported_for_endpoint The request asks for streaming, but the endpoint does not support it.
400 invalid_request_body The body is not a JSON object or not encoded in UTF-8.
402 insufficient_credit The organisation's credit is used up or lower than the estimated maximum cost of the request (including Noirdoc Shield, also on BYOK routes when Shield is active).
402 key_budget_exhausted This key's budget is used up for the current period or does not cover the estimated cost of the request.
403 model_not_allowed_for_key The model is not one of this key's allowed models.
403 provider_not_allowed_for_tenant The organisation counts as bound by professional secrecy (§ 203 StGB); this excludes every provider that offers this model.
403 provider_not_allowed_for_key The key's restrictions (providers, data residency, CLOUD Act, § 203) exclude every provider of this model.
403 starter_model_not_allowed The organisation is still using only its starter credit, and the model or its managed provider is not included in starter credit.
403 shield_violation Noirdoc Shield blocked the request before forwarding to the provider because an active protection filter configured with block matched; message names the triggered rule (secrets, pii, ner, injection or custom).
403 masking_not_supported_for_endpoint The endpoint supports neither Noirdoc Shield nor legacy masking, yet the policy is enforced or the request sends X-Noirdoc-Mask: on (and on /v1/images/generations also X-Noirdoc-Shield: on). During the legacy masking transition until 30.11.2026, this also affects /v1/embeddings and /v1/rerank on pre-existing organisations that have not switched to Shield yet.
403 model_not_billable The model has no complete price on record, so it cannot be used with credit.
404 model_not_available The model ID is not available to the organisation.
413 shield_input_too_large The text to inspect in this request exceeds the Shield service limit of 4 MiB of encoded text in a single call.
422 shield_uninspectable_content The Shield policy is enforced, and the request carries content that Shield cannot inspect as text (binary_document such as PDF or Office, media_not_inspectable such as images, audio or video, file_reference by ID or URL, file_too_large at 4 MiB or above, file_not_decodable or unrecognised_content). The gateway did not forward the request.
422 shield_config_invalid The organisation's stored Shield configuration is invalid (for example enforced without any active protection filter, or a pattern that fails compilation); the gateway did not forward the request.
502 provider_unreachable The gateway could not connect to the provider, or the connection dropped.
503 shield_unavailable The Noirdoc Shield inspection service is temporarily unreachable; the gateway never forwards a request that requires inspection uninspected (fail-closed). The response contains Retry-After with 5 seconds.
504 provider_timeout The provider did not answer within the gateway's timeout. The response contains Retry-After with 10 seconds.

OpenAI reference

OpenAI’s API reference describes all other request and response fields: Embeddings (checked on 30 September 2026).