Custom deployment service API Reference - OpenSearch - Alibaba Cloud Documentation Center

This topic describes how to call your custom deployment service.

General information

Endpoint

Obtain the endpoint (internet or private network) from the Service Deployment page in the console.

In the Actions column for the target service, click Call Information. The resulting dialog box shows the internet endpoint, private network endpoint, and corresponding access token.

Header

Content-Type: application/json
Authorization: Bearer ${your_workspace_api_key}
Token: ${your_service_deployment_token}. Obtain this token from Service Deployment > Call Information.

Multimodal embedding model

Request parameters

Parameter

Type

Description

Example

type

String

Valid values:

text: Specifies that the input is text.
image: Specifies that the input is an image.

image

data

List[String]

Each element contains text or an image to be converted into an embedding. We recommend submitting a maximum of 16 images per request. Supported image formats are PNG and JPEG. The required format is data:image/{format};base64,{base64_image}.

For an image:

["data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wCEAAoHCB..."]
For text:

["a", "b", "c"]

Request example

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <your_workspace_api_key>" \
-H "Token: <your_service_deployment_token>" \
"http://xxxxxx.opensearch.aliyuncs.com/v3/openapi/xxxxxx" \
-d '{
  "type": "image",
  "data": ["data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wCEAAoHCB..."]
}'

Note

A single request cannot contain both text and image inputs.

Response example

{
	"embeddings": [{
			"index": 0,
			"embedding": [0.02272411249577999, -0.0535903535783],
			"type": "image"
		}, {
			"index": 1,
			"embedding": [0.02272411249577999, -0.0535903535783],
			"type": "image"
		}
	]
}

Text embedding API

Request parameters

Parameter	Type	Required	Location	Description	Example
input	Array/String	Yes	body	The text inputs to convert. A maximum of 16 inputs are allowed per request. The maximum length of each input depends on the selected model. Empty strings are not supported.	["Science and technology are primary productive forces", "Open Search product documentation"]
input_type	String	No	body	Specifies the data type of the `input`. Valid values: `query` `document` The default value is `document`.	document
dimension	Int	No	body	The dimension of the output vector. Note This parameter applies only to custom models that have vector dimensionality reduction enabled. The specified dimension cannot exceed the dimension of the foundation model.	567

Request example

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <your_workspace_api_key>" \
-H "Token: <your_service_deployment_token>" \
"http://xxxxxx.opensearch.aliyuncs.com/v3/openapi/xxxxxx" \
-d '{
  "input":[
    "Science and technology are primary productive forces",
    "Open Search product documentation"
  ],
  "input_type" : "document",
  "dimension": 567 # This parameter applies only if vector dimensionality reduction is enabled on the model. Its value cannot exceed the foundation model's dimension.
}'

Response parameters

Parameter	Type	Description	Example
embeddings	List	An array of objects, where each object contains the resulting embedding for the corresponding input text.	`[ { "index": 0, "embedding": [0.003143,0.009750,...,-0.017395] }, {} ]`
embeddings[].index	Int	The index of the corresponding text in the `input` array.	0
embeddings[].embedding	List(Double)	The resulting vector embedding.	[0.003143,0.009750,...,-0.017395]

Response example

{
    "embeddings":[
        {
            "index":0,
            "embedding":[0.003143,0.009750,...,-0.017395]
        },
        {
            "index":1,
            "embedding":[]
        }
    ]
}

Reranker API

Request parameters

Parameter	Type	Required	Location	Description
query	String[]	Yes	body	The content of the query.
docs	List<String>	Yes	body	The documents to rerank against the query. A maximum of 16 documents are allowed per request.

Request example

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <your_workspace_api_key>" \
-H "Token: <your_service_deployment_token>" \
"http://xxxxxx.opensearch.aliyuncs.com/v3/openapi/xxxxxx" \
-d '{
    "query": "Open Search product documentation",
    "docs": [
        "Open Search product documentation",
        "Elasticsearch product documentation"
    ]
}'

Response parameters

Parameter	Type	Description	Example
scores	List<Double>	The score for each document in the `docs` array.	[0.9860338568687439,0.793461263179779]

Response example

{
    "scores":[
        0.9999276399612427,
        0.8209319710731506
    ]
}

Status codes

For more information, refer to the status codes for Open Search.