tencent cloud

Vector Embedding Model

Download
Focus Mode
Font Size
Last updated: 2026-11-17 14:27:53
AI-Translated & Reviewed

Overview

CMR is an AI gateway. CMR Embedding API provides gateway capabilities such as model access, request forwarding, protocol adaptation, routing, and rate limiting for different upstream Embedding models through a unified interface and authentication method. CMR itself does not generate vectors. Vectors are generated by the upstream model that is actually called. Input limits, vector dimensions, output format, vector quality, and model performance all depend on the capabilities of the selected model. Text and multimodal requests use the same entry point:
POST /v1/embeddings
Request Type
input Format
Description
Single text
string
Generate a vector for a single piece of text.
Batch text
string[]
Generate vectors for multiple pieces of text at a time.
Single Image-Text Input
object
Combine text and images in a single input.

Prerequisites

1. It is recommended to read Usage Constraints and Supported Model Providers in advance for relevant information.
2. A CMR instance has been created. For detailed instructions, see Creating a CMR Instance.
3. A BYOK instance has been created. For detailed instructions, see Creating a BYOK Instance.
4. A CMR API key has been created. For detailed instructions, see Creating a CMR API Key.
5. Vector embedding model association and CMR policy configuration have been completed. For detailed instructions, see Configuring Model Scheduling Management.

API Endpoint and Authentication

Request URL

POST {CMR_BASE_URL}/v1/embeddings
CMR_BASE_URL is the access address of the CMR instance. Use the value displayed in the console.

Request Header

Header
Required
Description
Authorization
Yes
Bearer <CMR_API_KEY>
Content-Type
Yes
Fixed as application/json.

Quick Start

cURL

curl --request POST "${CMR_BASE_URL}/v1/embeddings" \\
--header "Authorization: Bearer ${CMR_API_KEY}" \\
--header "Content-Type: application/json" \\
--data '{
"model": "cmr-text-embedding",
"input": "The weather in Shenzhen is nice today"
}'

Python

import os
import requests

response = requests.post(
f"{os.environ['CMR_BASE_URL']}/v1/embeddings",
headers={
"Authorization": f"Bearer {os.environ['CMR_API_KEY']}",
"Content-Type": "application/json",
},
json={
"model": "cmr-text-embedding",
"input": "The weather in Shenzhen is nice today",
},
timeout=30,
)
response.raise_for_status()
result = response.json()
print(result["data"][0]["embedding"])

Request Parameters

Basic Parameter

Parameter
Type
Required
Description
model
string
Yes
CMR logical model name or model alias. Available values are subject to the models associated in the console.
input
string | string[] | object
Yes
Text or image-text content for which vectors need to be generated.
dimensions
integer
No
Desired Dense vector dimension. Takes effect only when the selected model supports variable dimensions.
encoding_format
string
No
Return encoding of Dense vectors. Common values are float or base64, subject to the support of the selected model.
user
string
No
End user identifier, which can be used for business tracking or upstream risk control. Do not pass sensitive information such as passwords or tokens.

Text Input

Single text:
{
"model": "cmr-text-embedding",
"input": "Query text"
}
Batch text:
{
"model": "cmr-text-embedding",
"input": ["Query: How do I reset the password?", "Document: On the account security page, select Reset Password."]
}
For batch requests, you can map vectors to input items by using the data[].index field in the response.

Multimodal Input

You can combine text and images in a single input. Fill in the input field as shown in the following table:
Parameter
Type
Required
Description
input.type
string
Yes
Fixed to multimodal
input.content
object[]
Yes
Text and image content in the same input
input.content[].type
string
Yes
For text content, enter text. For image content, enter image_url.
input.content[].text
string
Required when type=text
Text Content
input.content[].image_url
object
Required when type=image_url
Image input object
input.content[].image_url.url
string
Required when type=image_url
Image input value. The value is not limited to HTTP/HTTPS URLs. Supported formats (such as public network URLs and Data URLs) depend on the selected upstream model. CMR passes through the value as requested.
Request sample:
{
"model": "cmr-multimodal-embedding",
"input": {
"type": "multimodal",
"content": [
{
"type": "text",
"text": "Red running shoes"
},
{
"type": "image_url",
"image_url": {
"url": "https://example.com/red-shoe.jpg"
}
}
]
},
"encoding_format": "float"
}
The preceding example only demonstrates how to pass an image by using a public URL. To check whether other image formats are supported, see the documentation of the selected upstream model. The current standard request does not support videos, multiple multimodal inputs, or mixing text and image arrays at the top level.

Provider Custom Request Parameters

CMR Standard fields include model, input, dimensions, encoding_format, and user. To pass Provider parameters outside CMR Standard, such as input_type and instruction, you can configure custom fields for pass-through.
For example, when input_type is allowed:
{
"model": "cmr-text-embedding",
"input": "How do I reset the password?",
"input_type": "query"
}
The names, types, and meanings of custom parameters are determined by the current Provider. Before changing the model or Provider, confirm that the same parameters still apply.

Response Parameters

Basic Response Fields

Parameter
Type
Returned or Not
Description
id
string
Yes
Identifier of this Embedding request.
created
integer
Yes
Response creation time, which is a Unix timestamp in seconds.
object
string
Yes
Fixed to list
data
object[]
Yes
List of vector results
model
string
Yes
Name of the CMR logical model used in the request
usage
object
No
Usage information returned by the upstream model. If the upstream model does not provide it, this field may be absent from the response.

Response Vector Results

Parameter
Type
Returned or Not
Description
data[].object
string
Yes
Fixed to embedding
data[].index
integer
Yes
Index of the input corresponding to the result, starting from 0
data[].embedding
number[] | string
No
Dense vector. It may be a string when encoded output is used.
data[].sparse_embedding
object[]
No
Sparse vector, listing only non-zero positions and their weights
data[].multi_embedding
number[][] | string | object
No
Multi-vector result. The specific format is subject to the return value of the selected model.
Each data[] result contains at least one of the following types: Dense, Sparse, or Multi-vector. When multiple vector types are supported by the selected model, the same result can contain multiple vector types simultaneously.
The meaning of each element in sparse_embedding is as follows:
Parameter
Type
Returned or Not
Description
index
integer
Yes
Subscript of a non-zero dimension
value
number
Yes
Weight of the dimension
token
string
No
Corresponding Token returned by the upstream model

Provider Custom Response Parameters

In addition to the fields above, the response may retain extra information returned by the upstream Provider. For example:
The request_id at the top level of the response.
The type field in data[] that indicates the vector type.
These fields are subject to the actual response. After the model or Provider is changed, they may no longer be returned or their meanings may change.

Response Example

The following example only shows the field format. The vector values, vector dimensions, and Token usage are subject to the actual response.

Dense Vector

{
"id": "emb-7f3a2c10",
"created": 1787385661,
"object": "list",
"data": [
{
"object": "embedding",
"index": 0,
"embedding": [0.012, -0.034, 0.021]
}
],
"model": "cmr-text-embedding",
"usage": {
"prompt_tokens": 4,
"total_tokens": 4
}
}

Dense + Sparse Vector

{
"id": "emb-a1b2c3d4",
"created": 1787385661,
"object": "list",
"data": [
{
"object": "embedding",
"index": 0,
"embedding": [0.018, -0.041, 0.007],
"sparse_embedding": [
{
"index": 18452,
"value": 0.73,
"token": "Database"
}
]
}
],
"model": "cmr-hybrid-embedding",
"usage": {
"total_tokens": 9
},
"request_id": "provider-request-id"
}

Dense + Multi-vector

{
"id": "emb-9e8d7c6b",
"created": 1787385661,
"object": "list",
"data": [
{
"object": "embedding",
"index": 0,
"embedding": [0.016, -0.028, 0.031],
"multi_embedding": [
[0.021, -0.013, 0.009],
[0.008, 0.034, -0.017]
]
}
],
"model": "cmr-multimodal-embedding"
}

Error Response

The CMR Embedding API uses a unified error response format:
{
"error": {
"message": "Invalid input: input is required.",
"type": "invalid_request_error",
"param": "input",
"code": "400"
}
}
Parameter
Description
error.message
Error description
error.type
Error type. The specific value may vary depending on the error source.
error.param
Request parameter related to the error. It may be empty when no specific parameter is identified.
error.code
Error code. It is currently common as an HTTP status code in string format.
CMR may retain safely processed upstream additional information in errors. Clients should handle failures primarily based on HTTP status codes and should not rely on upstream error messages remaining unchanged.
Common HTTP status codes:
HTTP Status Code
Common Scenes
Recommendation
400
Invalid JSON or parameter format, unsupported input type, invalid CMR logical model name, or the upstream model rejects the current parameter.
Correct the request instead of retrying blindly.
401
The API Key is invalid or expired, or upstream authentication failed.
Check the API Key and related credentials.
403
Missing API Key, invalid authentication header format, or no permission to access the current CMR instance, model, or upstream resource.
Check the Authorization Header and permission configuration.
404
The upstream model, resource, or API path does not exist.
Check the selected model and Provider configuration.
408
Request or upstream call timeout.
Retry when the business allows.
429
CMR rate limiting, upstream quota exceeded, or no deployment currently available
Refer to Retry-After (if present) and retry with a backoff policy.
500
CMR internal error, or CMR failed to connect to the upstream.
Record the request identifier and contact support personnel.
502
The upstream response is invalid, or the response does not match the current protocol configuration.
Retry with a backoff policy; contact support personnel if the issue persists.
503
The upstream service or the current protocol configuration is temporarily unavailable.
Retry with a backoff policy.
504
Upstream gateway timeout
Retry with a backoff policy.

Help and Support

Was this page helpful?

Help us improve! Rate your documentation experience in 5 mins.

Feedback