Retrieve images by image or text using an API - AnalyticDB

The Image Search API retrieves similar images from an image library. It supports searching by image (with a Base64 image input) and by text (with a text description). You can also apply tag filters using the tag_filter parameter.

API overview

Note: All API endpoints share the prefix /api/v1/operators/image-search.

API name	Method	Path
Search by image in a specific image library	POST	`/api/v1/operators/image-search/search/by-image`
Search by text in a specific image library	POST	`/api/v1/operators/image-search/search/by-text`

Search by image

Request method: POST

Request path: /api/v1/operators/image-search/search/by-image

API description: Searches a specific image library for images that are visually similar to a query image. The query image must be provided as a Base64-encoded string.

Request parameters

Parameter	Type	Required	Default	Description
`library_name`	string	Yes	None	The name of the target image library.
`image_base64`	string	Yes	None	The Base64-encoded string of the query image.
`top_k`	int	No	`10`	The maximum number of results to return.
`tag_filter`	list / object	No	None	Tag filtering conditions. For syntax details, see `tag_filter` syntax.
`return_frame`	bool	No	`true`	Specifies whether to return the Base64-encoded image content in the results. Set this parameter to `false` to reduce payload size.

Request example

curl -X POST 'http://localhost:8000/api/v1/operators/image-search/search/by-image' \
  -H 'Content-Type: application/json' \
  -d '{
    "library_name": "shop_a_tops",
    "image_base64": "/9j/4AAQSkZJRgABAQAAAQABAAD...",
    "top_k": 5,
    "tag_filter": [
      {"field": "color", "op": "in", "value": ["red", "blue"]},
      {"field": "season", "op": "=", "value": "summer"}
    ]
  }'

Response

HTTP status codes

Status code	Description
200	The search was successful. The results list may be empty.
400	Bad Request. The request parameters are invalid.
404	Not Found. The specified image library does not exist.
500	Internal server error.

data field

Field	Type	Description
`results`	list[object]	A list of search results sorted by similarity score in descending order. If no matches are found, the list is empty.
`results[].image_id`	string	The unique identifier of the image.
`results[].image_uri`	string	The image resource identifier (the original value you provided during import).
`results[].image_base64`	string / null	The Base64-encoded image content. This field is `null` if `return_frame=false` or if the image library does not store the content.
`results[].score`	float	The similarity score, ranging from 0.0 to 1.0, where a higher value indicates greater similarity. A score above 0.9 typically indicates a high degree of similarity, while a score between 0.7 and 0.9 suggests moderate similarity.
`results[].tags`	object	The custom tags associated with the image.

Response example (with results)

{
  "status": "SUCCESS",
  "message": null,
  "data": {
    "results": [
      {
        "image_id": "img001",
        "image_uri": "https://example.com/tops/img001.jpg",
        "image_base64": "/9j/4AAQSkZJRgABAQAAAQABAAD...",
        "score": 0.962,
        "tags": {
          "color": "white",
          "season": "summer"
        }
      },
      {
        "image_id": "img002",
        "image_uri": "https://example.com/tops/img002.jpg",
        "image_base64": "/9j/4AAQSkZJRgABAQAAAQABAAD...",
        "score": 0.891,
        "tags": {
          "color": "blue",
          "season": "summer"
        }
      }
    ]
  }
}

Response example (no results, e.g., when no item is detected in item_search mode)

{
  "status": "SUCCESS",
  "message": null,
  "data": {
    "results": []
  }
}

Search by text

Request method: POST

Request path: /api/v1/operators/image-search/search/by-text

API description: Searches a specific image library for images that semantically match a text description.

The API supports multilingual input. For services deployed in the Chinese mainland, the server automatically translates the input text into Chinese before performing the search.

Note: Search by text is available only for image libraries in general_search mode. The API returns an HTTP 400 error if used with libraries in other modes.

Request parameters

Parameter	Type	Required	Default	Description
`library_name`	string	Yes	None	The name of the target image library (must be in `general_search` mode).
`query_text`	string	Yes	None	Search for text descriptions, such as `white short-sleeve T-shirt` or `a white short-sleeve T-shirt`.
`top_k`	int	No	`10`	The maximum number of results to return.
`tag_filter`	list / object	No	None	Tag filtering conditions. For syntax details, see `tag_filter` syntax.
`return_frame`	bool	No	`true`	Specifies whether to return the Base64-encoded content of the image in the result. Set this parameter to `false` to reduce the amount of data transferred.

Request example

curl -X POST 'http://localhost:8000/api/v1/operators/image-search/search/by-text' \
  -H 'Content-Type: application/json' \
  -d '{
    "library_name": "general_clothing",
    "query_text": "a white short-sleeve T-shirt",
    "top_k": 10,
    "tag_filter": [
      {"field": "season", "op": "=", "value": "summer"},
      {"field": "category", "op": "!=", "value": "pants"}
    ]
  }'

Response

HTTP status codes

Status code	Description
200	The search was successful. The results list may be empty.
400	Bad Request. The request parameters are invalid, or the image library does not support search by text because it is not in `general_search` mode.
404	Not Found. The specified image library does not exist.
500	Internal server error.

The data field has the same structure as in the search-by-image response.

Response example

{
  "status": "SUCCESS",
  "message": null,
  "data": {
    "results": [
      {
        "image_id": "img001",
        "image_uri": "https://example.com/tops/img001.jpg",
        "image_base64": "/9j/4AAQSkZJRgABAQAAAQABAAD...",
        "score": 0.943,
        "tags": {
          "color": "white",
          "season": "summer"
        }
      }
    ]
  }
}

Failure response example (HTTP 400)

{
  "status": "MODE_NOT_SUPPORTED",
  "message": "Image library 'shop_a_tops' is in item_search mode and does not support text-to-image search.",
  "data": null
}

`tag_filter` syntax

The search APIs support result filtering using the tag_filter parameter. tag_filter uses structured conditional expressions to support features like exact matching, substring matching, and logical combinations (AND/OR).

Condition object

Each filter condition is a structured JSON object:

{"field": "color", "op": "=", "value": "red"}

Field	Type	Required	Default	Description
`field`	string	Yes	None	The name of the field within the `tags` object.
`op`	string	Yes	None	The operator. See the operators table below.
`value`	string / list	Yes	None	The match value is an array for `in` / `not in`, and a string otherwise.

Operators

op	Description	Value type	Example
`=`	Exact match	string / number	`{"field": "color", "op": "=", "value": "red"}`
`!=`	Not equal to	string / number	`{"field": "color", "op": "!=", "value": "black"}`
`>`	Greater than	string / number	`{"field": "score", "op": ">", "value": 0.5}`
`>=`	Greater than or equal to	string / number	`{"field": "score", "op": ">=", "value": 0.9}`
`<`	Less than	string / number	`{"field": "score", "op": "<", "value": 1.0}`
`<=`	Less than or equal to	string / number	`{"field": "score", "op": "<=", "value": 0.95}`
`like`	Contains substring	string	`{"field": "color", "op": "like", "value": "re"}`
`not like`	Does not contain substring	string	`{"field": "color", "op": "not like", "value": "dark"}`
`in`	Matches any value in a list	list	`{"field": "color", "op": "in", "value": ["red", "blue"]}`
`not in`	Does not match any value in a list	list	`{"field": "color", "op": "not in", "value": ["black", "grey"]}`

Logical combinations

Array (AND): Conditions in a JSON array are implicitly combined with AND.
{"or": [...]} = OR: Conditions in the or array are combined with OR.
Nested combinations are supported.

Examples

AND combination (most common)

[
  {"field": "color", "op": "=", "value": "red"},
  {"field": "season", "op": "=", "value": "summer"}
]

Meaning: color = "red" AND season = "summer"

Cross-field OR

{
  "or": [
    {"field": "color", "op": "=", "value": "red"},
    {"field": "season", "op": "=", "value": "summer"}
  ]
}

Meaning: color = "red" OR season = "summer"

Nested AND + OR

[
  {"field": "category", "op": "!=", "value": "pants"},
  {
    "or": [
      {"field": "color", "op": "=", "value": "red"},
      {"field": "season", "op": "=", "value": "summer"}
    ]
  }
]

Meaning: category != "pants" AND (color = "red" OR season = "summer")

E-commerce example (filter by category, color, and price range)

[
  {"field": "category", "op": "=", "value": "T-shirt"},
  {"field": "color", "op": "in", "value": ["white", "beige"]},
  {"field": "price", "op": ">=", "value": 50},
  {"field": "price", "op": "<=", "value": 200}
]

Meaning: category = "T-shirt" AND color IN ["white", "beige"] AND price >= 50 AND price <= 200

API overview

Search by image

Request parameters

Response

Search by text

Request parameters

Response

tag_filter syntax

Condition object

Operators

Logical combinations

Examples

`tag_filter` syntax