Embeddings
POST https://api-staging.heimdallm.com/api/v1/embeddingsOpenAI-compatible embeddings. Requires a bearer API key. Use a model whose
output modality is embeddings — filter the model list, look for
"output_modalities": ["embeddings"] in the catalogue, or list them directly:
GET https://api-staging.heimdallm.com/api/v1/embeddings/modelsRouting and provider preferences work as on chat; an endpoint that does not serve embeddings answers
502, and routing moves on to one that does.
Request body
| Field | Type | Notes |
|---|---|---|
model | string | Required. |
input | string / string[] / integer[] / integer[][] / object[] | Required. A string array may hold up to 2048 entries; integer arrays are pre-tokenized input; an object array is multimodal — see below. |
input_type | string | Hint at how the vectors will be used, e.g. search_query, search_document. |
encoding_format | string | float (default) or base64. |
dimensions | integer | Truncate the output vectors to a width the model declares. A width no live endpoint of the model declares is refused before an engine is reached; the model object's supported_dimensions names what is available. |
user | string (≤ 256) | Opaque end-user identifier. |
provider | object | Provider preferences. |
Multimodal input
An item of the input array may be { "content": [...] }, whose parts are embedded into one vector
together:
| Part | Input modality |
|---|---|
{ "type": "text", "text": "…" } | text |
{ "type": "image_url", "image_url": { "url": "…" } } | image |
{ "type": "input_audio", "input_audio": { "data": "…", "format": "wav" } } | audio |
{ "type": "input_video", "input_video": { "data": "…", "format": "mp4" } } | video |
{ "type": "input_file", "input_file": { "data": "…", "format": "pdf" } } | file |
data is the bytes base64-encoded and format is the container they arrived in. Input modalities
are declared per model, so a request carrying a part whose modality the model does not declare is
refused with 400 before any provider is called. A text part is judged against nothing: it asks
for what a plain string input asks for.
A text part is routed like a plain string but is not always embedded like one. A multimodal model may
wrap a content item in the turns its chat template defines, where a plain string is tokenised as it
stands, so the same words can embed to different vectors through the two forms. On
tencent/wemm-embedding-2b, the text a red square embeds 0.1189 apart by cosine distance as a plain
string and as a content item holding only that text. Keep an index and the queries run against it on one
form: embed images and their text queries as content items, or embed text on both sides as plain
strings, and do not search an index built from one with vectors from the other. Input forms and
bases sets out which shapes share a basis.
Example
curl https://api-staging.heimdallm.com/api/v1/embeddings \
-H "Authorization: Bearer $HEIMDALL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "baai/bge-m3",
"input": ["The quick brown fox", "jumps over the lazy dog"]
}'{
"object": "list",
"id": "gen-01J8Z0X2QZ",
"data": [
{ "object": "embedding", "index": 0, "embedding": [0.0132, -0.0074, 0.0219] },
{ "object": "embedding", "index": 1, "embedding": [0.0087, 0.0301, -0.0158] }
],
"model": "baai/bge-m3",
"provider": "ImpCC",
"usage": { "prompt_tokens": 12, "total_tokens": 12, "cost": 0.00000012 }
}
(Vectors are truncated here for readability; a real response carries the model's full dimensionality.)
Response fields
| Field | Type | Notes |
|---|---|---|
object | string | list. |
id | string | The marketplace's generation id, as X-Generation-Id also carries. (Heimdallm) |
data[].object | string | embedding. |
data[].index | integer | Position of the corresponding input. |
data[].embedding | number[] / string | The vector — a base64 string when encoding_format is base64. |
model | string | The model that served the request. |
provider | string | The serving provider's display name. (Heimdallm) |
usage.prompt_tokens | integer | Reported input tokens; omitted when unreported. |
usage.total_tokens | integer | Equals reported prompt_tokens; omitted when unreported. |
usage.prompt_tokens_details | object | Per-modality share of prompt_tokens (text_tokens, image_tokens, audio_tokens, video_tokens, file_tokens). Present only when the input mixed modalities and the endpoint reported the split. |
usage.cost | number | Exact charge in USD. (Heimdallm) |
The X-Generation-Id and X-Provider-Name headers are sent as on chat completions. For model
choice, batching and pricing advice, see Working with embeddings.
Unreported usage remains unknown. usage.cost can be zero after financial finalization while token
counts are omitted; an explicitly reported zero remains 0.