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

This topic describes how to call custom deployment services through API.

General information

URI

Go to Service Deployment > Manage to obtain the access domain name (Internet or private network domain name).

Header

Content-Type: application/json
Authorization: Bearer ${workspace API key}
Token: ${service deployment Token}, as shown in the figure above, you can obtain it from Service Deployment > Call Information.

Multimodal embedding models

Request parameters

Field name

Type

Description

Example

type

String

Valid values:

text: text.
image: image.

image

data

List[String]

Each element represents a text to be vectorized or an image. We recommend that you do not include more than 16 images in a single request. Images support png and jpeg formats, in the format of data:image/{format};base64,{base64_image}

Image type:
["data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wCEAAoHCB..."]
Text type:
["a", "b", "c"]

Request example

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Your API Key" \
-H "Token: Replace with service deployment Token" \
"http://xxxxxx.opensearch.aliyuncs.com/v3/openapi/xxxxxx" \
-d '{
  "type": "image",
  "data": ["data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wCEAAoHCB..."]
}'

Note

You cannot mix text and image in a single request.

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 name	Type	Required	Position	Description	Example
input	Array/String	Yes	body	Supports multiple text inputs, up to 16 per request. The length of each text depends on the selected model. Empty strings are not supported.	["Science and technology are the primary productive forces","opensearch product documentation"]
input_type	String	No	body	Specifies the data type of input, valid values: query document Default value: document	document
dimension	Int	No	body	Output dimension. Note This parameter takes effect only when the deployed model is a customized model with vector dimensionality reduction enabled, and the value cannot be greater than the dimension of the foundation model.	567

Request example

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Your API Key" \
-H "Token: Replace with service deployment Token" \
"http://xxxxxx.opensearch.aliyuncs.com/v3/openapi/xxxxxx" \
-d '{
  "input":[
    "Science and technology are the primary productive forces",
    "opensearch product documentation"
  ],
  "input_type" : "document",
  "dimension": 567 # This takes effect only when vector dimensionality reduction training is enabled, and the dimension cannot be greater than that of the foundation model
}'

Response parameters

Field	Type	Description	Example
embeddings	List	The output of the request. This parameter is an array. Each element of the array corresponds to a segment of input text.	`[ { "index": 0, "embedding": [0.003143,0.009750,omitted,-0.017395] }, {} ]`
embeddings[].index	Int	The ordinal number of the corresponding request text in the input.	0
embeddings[].embedding	List(Double)	Vectorization result.	[0.003143,0.009750,omitted,-0.017395]

Response example

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

Reranker API

Request parameters

Parameter name	Type	Required	Position	Description
query	String[]	Yes	body	Query content.
docs	List<String>	Yes	body	Multiple document contents, not exceeding 16 docs.

Request example

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Your API Key" \
-H "Token: Replace with service deployment Token" \
"http://xxxxxx.opensearch.aliyuncs.com/v3/openapi/xxxxxx" \
-d '{
    "query": "opensearch product documentation",
    "docs": [
        "opensearch product documentation",
        "elasticsearch product documentation"
    ]
}'

Response parameters

Parameter name	Parameter type	Description	Example
scores	List<Double>	Score for each doc in the docs	[0.9860338568687439,0.793461263179779]

Response example

{
    "scores":[
        0.9999276399612427,
        0.8209319710731506
    ]
}

Status codes

For more information, see AI Search Open Platform status codes.