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 | — | Embedding model ID from the Model Market. Model names are case-insensitive and the server normalizes them. Options / constraints: Use a currently available model ID from the model details page. |
input | string | string[] | Yes | — | Text to convert into vectors. Accepts one or multiple inputs. Options / constraints: For batch input, each array item maps to one vector in the returned data array. |
encoding_format | string | No | — | Vector encoding format passed to the downstream provider. Leave it blank to use the provider default. Options / constraints: float, base64. |
dimensions | integer | No | — | Number of dimensions in the returned vectors. Leave it blank to use the provider default. Options / constraints: Only some models support this parameter. Check the model details page. |
extra_body | object | No | — | Extension field for unified-API routing, billing, and policy controls. Options / constraints: provider, consume_type. |
extra_body.provider | object | No | — | Provider selection, filtering, sorting, and metric ranges. Options / constraints: The platform applies filters in this order: only → ignore → range filters → order → sort. |
extra_body.provider.only | string[] | No | — | Provider allowlist. Selects only from the specified set. Options / constraints: Provider names are case-sensitive. |
extra_body.provider.ignore | string[] | No | — | Provider denylist. Excludes providers from the candidate set. Options / constraints: Returns 422 if the same provider appears in both only and ignore. |
extra_body.provider.order | string[] | No | — | Preferred provider order. Options / constraints: Provider names are case-sensitive. |
extra_body.provider.sort | string | string[] | No | — | Provider sort policy. Accepts multiple keywords; earlier array items have higher priority. Options / constraints: input_price, output_price, throughput, latency, input_length. |
extra_body.provider.input_price_range | [number, number] | No | — | Limits the input-price range. Options / constraints: Unit: ¥ per 1M tokens. Example: [1, 2]. |
extra_body.provider.output_price_range | [number, number] | No | — | Limits the output-price range. Options / constraints: Unit: ¥ per 1M tokens. |
extra_body.provider.throughput_range | [number, number] | No | — | Limits the real-time throughput range. Options / constraints: Unit: tokens/s. |
extra_body.provider.latency_range | [number, number] | No | — | Limits the real-time latency range. Options / constraints: Unit: seconds. |
extra_body.provider.input_length_range | [number, number] | No | — | Limits the range of maximum input lengths supported by providers. Options / constraints: Unit: tokens. |
extra_body.provider.allow_filter_prompt_length | boolean | No | true | Whether to automatically filter providers by the input length for this request. Options / constraints: true / false. |
extra_body.provider.allow_fallbacks | boolean | No | true | Whether to fall back to other available channels according to the sort policy when no filter matches. Options / constraints: true / false. |
extra_body.enable_thinking | boolean | No | — | Embedding requests accept this field but ignore it. Options / constraints: true / false. |
extra_body.consume_type | string | No | — | Labels the purpose of this call for billing and request tracking. Options / constraints: api or chat. Use api for Embedding calls. |
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[] | string | No | — | Returned vector data. When the encoding format is base64, this may be a string. |
data[].index | integer | No | — | Position of the input corresponding to this vector; indexing starts at 0 (zero-based). |
usage.prompt_tokens | integer | No | — | Number of tokens consumed by the input text. If the downstream provider omits this value, the platform may estimate it from the request content. |
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. |
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.
Routing applies filters in this order: only, ignore, range filters, order, then sort. Price, throughput, latency, and input-length ranges depend on real-time platform metrics. When metrics are unavailable, the platform may skip a filter or use a less specific sort.
Set consume_type to api for easier billing and tracking. Before writing vectors, use consistent text chunking and cleaning and record the document version. Use the same model, dimensions, and preprocessing rules for writes and queries.
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": {
"only": [],
"ignore": [],
"order": [],
"sort": ["throughput"],
"input_price_range": [],
"output_price_range": [],
"throughput_range": [],
"latency_range": [],
"input_length_range": []
},
"consume_type": "api"
}
}'