The Embedding endpoint converts text into vectors for semantic search, knowledge-base retrieval, deduplication, and similarity calculations.
https://api.tokensmarket.ai/v1POST /embeddingsThe endpoint remains fixed. Use the parameter documentation on this page to replace the model ID and request data.
${base_url}/embeddingsEmbedding requests use a Bearer API Key for authentication and send the request body as JSON.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
Authorization | string | Yes | — | Append the current workspace API Key after Bearer. Options / constraints: Bearer <API_KEY>. |
Content-Type | string | Yes | application/json | Send the request body as JSON. |
Input can be a single text string or an array of strings. Use the same model and dimensions throughout indexing, querying, and related workflows.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
model | string | Yes | — | The Embedding model ID in Model Market; it is case-sensitive. Options / constraints: An exact copy of the model ID currently available on the model details page. |
input | string | string[] | integer[] | integer[][] | Yes | — | An array of text or model-backed tokens that needs to be converted to a vector. Options / constraints: When input in batches, each item in the array corresponds to a vector in data. |
encoding_format | string | No | float | Vector encoding format. Options / constraints: Only float is supported; base64 returns HTTP 400 |
dimensions | integer | No | — | Returns the dimensions of the vector. Options / constraints: Must be a positive number and is only supported by some models. |
user | string | No | — | Optional end user ID. Options / constraints: Do not include an API Key or sensitive personal information. |
extra_body | object | No | — | Extension fields for the Unified API. Options / constraints: provider. |
extra_body.provider | object | No | — | Service provider selection, filtering, sorting and indicator range. Options / constraints: Filter application order: ignore → ranges → only → sort → order. |
extra_body.provider.only | string[] | No | — | Service provider whitelist, select only within the specified set. Options / constraints: Service provider names are case-sensitive. |
extra_body.provider.ignore | string[] | No | — | Service provider blacklist, excluded from candidate set. Options / constraints: Non-empty only and ignore must not overlap; if verification fails, HTTP 400 / invalid_request will be returned. |
extra_body.provider.order | string[] | No | — | Boosts the priority of the specified provider last. Options / constraints: Service provider names are case-sensitive. |
extra_body.provider.sort | string | string[] | No | — | The service provider sorting strategy supports multiple keywords, and the ones in front of the array have higher priority. Options / constraints: input_price, output_price, throughput, latency, input_length. |
extra_body.provider.input_price_range | [number, number] | No | — | Limits the current account's input price range. Options / constraints: Unit: USD per million tokens; the range must contain exactly two nonnegative values and its lower bound must not exceed its upper bound. |
extra_body.provider.output_price_range | [number, number] | No | — | Limits the current account's output price range. Options / constraints: Unit: USD / million tokens; range=[] is illegal. |
extra_body.provider.throughput_range | [number, number] | No | — | Limit the real-time throughput range. Options / constraints: Unit: tokens/s. |
extra_body.provider.latency_range | [number, number] | No | — | Limit real-time latency range. Options / constraints: Unit: seconds. |
extra_body.provider.input_length_range | [number, number] | No | — | Limit the maximum input length range supported by the service provider. Options / constraints: Unit: Token. |
extra_body.provider.allow_fallbacks | boolean | No | — | Defaults to false when only is non-empty; otherwise defaults to true. Options / constraints: true only relaxes only, range, sort, order; does not relax ignore, permissions, endpoint capabilities, or channel availability. |
The response is compatible with the OpenAI Embeddings API and includes information about the provider that served the request.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
model | string | No | — | Model ID actually used for this request. |
data | array | No | — | Array of vector results. Each item maps by index to a text string in the input array. |
data[].object | string | No | — | Vector object type. Options / constraints: embedding. |
data[].embedding | number[] | No | — | Floating point vector data. |
data[].index | integer | No | — | Position of the input corresponding to this vector; indexing starts at 0 (zero-based). |
usage.prompt_tokens | integer | No | — | The number of input tokens when the protocol returns. |
usage.total_tokens | integer | No | — | Total number of tokens counted for this call. |
provider | string | No | — | Information about the provider channel that served the request. Options / constraints: May only appear in non-streaming JSON. |
input can be a single text string or an array of strings. Only some models support dimensions. Index creation, queries, and index rebuilds must use the same model, dimensions, and preprocessing rules.
The routing is uniformly placed in extra_body.provider. When allow_fallbacks=false, only route within the candidate set formed by only and each range; when true and the preferred set is empty, only, range, sort, and order can be relaxed, but ignore, model permissions, endpoint capabilities, or channel availability will never be relaxed.
Unify text segmentation, cleaning and recording document versions before writing; query and write use the same model, dimensions and preprocessing rules.
The examples use placeholders. Replace them with a currently available model ID from the model details page, and keep your API Key in a server-side environment variable.
curl https://api.tokensmarket.ai/v1/embeddings \
-H "Authorization: Bearer $TOKEN_MARKET_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "<MODEL_ID>",
"input": ["First document for embedding", "Second document for embedding"],
"encoding_format": "float",
"dimensions": 1536,
"extra_body": {
"provider": {
"sort": ["throughput"],
"latency_range": [0, 2]
}
}
}'