Skip to content
Numes

API reference · Create embedding

Embeddings

Create embedding

Turn text, token arrays or multimodal content into embedding vectors.

POSThttps://api.numes.ai/api/v1/embeddings

Vectors come back sorted by index; encoding_format: "base64" returns each vector base64-encoded. dimensions, encoding_format and input_type are forwarded to the endpoint; with provider.require_parameters: true, only endpoints that declare them are used. Find embedding models with GET /models?output_modalities=embeddings. Your account's request policy applies to text inputs; images, files, audio and token arrays aren't inspected. Guide: Embeddings.

Authorization

AuthorizationheaderRequired

Bearer inference key. Charges settle in the key's billing currency. Authorization: Bearer $NUMES_API_KEY

Headers

X-Request-Idstring

Correlation ID, not an idempotency key. Inference request IDs recorded with a generation are unique per account. A traffic-admitted request reusing a recorded ID returns 400 invalid_request. Traffic admission rejection takes precedence over this conflict, including for reused IDs; it performs no generation lookup and writes no generation, result or attempt. Rate-limit rejection returns 429 rate_limited with Retry-After; an inference limiter outage retains 500 server.

Length1–128

Request body

application/json

The contract declares a 10 MiB body limit. The size the service enforces is listed in Limits.

modelstringRequired
Length3–393
Pattern^[a-z0-9][a-z0-9._-]{0,99}/[A-Za-z0-9][A-Za-z0-9._:-]{0,291}$
inputstring | array<string> | array<integer> | array<array<integer>> | array<array<object>>Required

One of 5 shapes

ShowOption 1string

A string value.

ShowOption 2array<string>

A array<string> value.

ShowOption 3array<integer>

A array<integer> value.

ShowOption 4array<array<integer>>

A array<array<integer>> value.

ShowOption 5array<array<object>>

A array<array<object>> value.

dimensionsinteger
Range1–65,536
encoding_formatenum<string>
Default"float"
One offloatbase64
input_typestring
Length≤ 128
providerobject
Show11 child attributes
orderarray<string>
Items≤ 100
Itemlength 1–256
allow_fallbacksboolean
Defaulttrue
require_parametersboolean
Defaultfalse
data_collectionenum<string>
One ofallowdeny
zdrboolean
onlyarray<string>
Items≤ 100
Itemlength 1–256
ignorearray<string>
Items≤ 100
Itemlength 1–256
quantizationsarray<string>
Items≤ 100
Itemlength 1–256
regionsarray<string>

Numes extension filtering endpoint-declared country or region identifiers.

Items≤ 64
Uniqueitems
Itempattern ^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$
sortenum<string>

Deterministic provider sort. `quality` is a deliberate Numes compatibility extension that ranks endpoints by exact task-scoped content-free validation evidence; it is opt-in and never changes the default routing order.

One ofpricethroughputlatencyquality
max_priceobject
Show2 child attributes
promptnumber
Range≥ 0
completionnumber
Range≥ 0

Responses

200Indexed embedding vectors and exact usageapplication/json

Headers

X-Request-Idstring

Correlation identifier assigned or accepted by the service.

X-Generation-Idstring

Generation identifier when inference reached generation setup.

BodyEmbeddingResponseapplication/json

idstringRequired
objectstringRequired
Value"list"
modelstringRequired
Pattern^[a-z0-9][a-z0-9._-]{0,99}/[A-Za-z0-9][A-Za-z0-9._:-]{0,291}$
dataarray<object>Required
Show3 child attributes
objectstringRequired
Value"embedding"
indexintegerRequired
Range≥ 0
embeddingarray<number> | stringRequired

One of 2 shapes

ShowOption 1array<number>

A array<number> value.

ShowOption 2string

A string value.

usageobjectRequired
Show3 child attributes
prompt_tokensintegerRequired
Range≥ 0
total_tokensintegerRequired
Range≥ 0
costnumberRequired
Range≥ 0
503No eligible provider can serve the request. Unknown, unpublished, currency-mismatched and unauthorized shared model IDs receive the same bounded response (`error.code` 503, `error.metadata.error_type` "provider_unavailable", message "no provider is available"). Inference and encrypted resolution do not classify model existence after routing fails. Earlier validation and authorization errors remain unchanged. An interrupted server execution while the original HTTP caller remains connected also uses 503 provider_unavailable with the fixed message "service temporarily unavailable". Once streaming has started, the error is in-band and the HTTP status remains 200. If an otherwise eligible USD-indexed Bitcoin offer is blocked by an unavailable market reference, or its reference expires before dispatch, the response instead uses 503 with error_type "bitcoin_reference_price_unavailable" and message "Bitcoin pricing is unavailable. Try again shortly."application/json

Headers

X-Request-Idstring

Correlation identifier assigned or accepted by the service.

BodyErrorResponseapplication/json

errorobjectRequired
Show3 child attributes
codeintegerRequired
messagestringRequired
metadataobject
openrouter_metadataobject
ErrorCompatible error envelopeapplication/json

Headers

X-Request-Idstring

Correlation identifier assigned or accepted by the service.

Retry-Afterinteger

Optional delay in seconds for retryable rate or availability errors.

Range≥ 1

BodyErrorResponseapplication/json

errorobjectRequired
Show3 child attributes
codeintegerRequired
messagestringRequired
metadataobject
openrouter_metadataobject