Develop / Reference
Embeddings
Generates vector embeddings in the OpenAI format and inspects the input with Noirdoc Shield before forwarding when Shield is active.
/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.
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."
]
}'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))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
| Area | Behaviour |
|---|---|
| Model | The 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. |
| Provider | The X-Noirdoc-Provider header in the response names the provider. See Providers & routing. |
| Noirdoc Shield | When 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). |
| Streaming | None. The gateway answers "stream": true with 400 streaming_not_supported_for_endpoint. |
| Billing | The 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. |
| Headers | The 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).