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. |
POST {CMR_BASE_URL}/v1/embeddings
Header | Required | Description |
Authorization | Yes | Bearer <CMR_API_KEY> |
Content-Type | Yes | Fixed as application/json. |
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"}'
import osimport requestsresponse = 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"])
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. |
{"model": "cmr-text-embedding","input": "Query text"}
{"model": "cmr-text-embedding","input": ["Query: How do I reset the password?", "Document: On the account security page, select Reset Password."]}
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. |
{"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"}
{"model": "cmr-text-embedding","input": "How do I reset the password?","input_type": "query"}
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. |
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. |
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 |
{"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}}
{"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"}
{"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": {"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. |
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. |
Was this page helpful?
You can also Contact sales or Submit a Ticket for help.
Help us improve! Rate your documentation experience in 5 mins.
Feedback