Image Retrieval

API Overview

Note: All APIs use the prefix /api/v1/operators/image-search.

API Name	Method	Path
Search by image in a specified image gallery	POST	`/api/v1/operators/image-search/search/by-image`
Text-to-image search in a specified image gallery	POST	`/api/v1/operators/image-search/search/by-text`

1. Search by Image

Request method: POST

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

Description: Retrieve visually similar images from a specified image gallery using a Base64-encoded image as input.

Request Parameters

Parameter	Type	Required	Default	Description
`library_name`	string	Yes	None	Target image gallery name.
`image_base64`	string	Yes	None	Base64-encoded string of the query image.
`top_k`	int	No	`10`	Maximum number of results to return.
`tag_filter`	list [object]	No	None	Tag-based filter conditions. Uses the tag_filter filtering syntax.
`return_frame`	bool	No	`true`	Include Base64-encoded image content in the response. Set to `false` to reduce data transfer.

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": "=", "value": "red"},
      {"field": "season", "op": "=", "value": "summer"}
    ]
  }'

Response

HTTP status codes

Status Code	Description
200	Search succeeded (results may be an empty list).
400	Invalid request parameters.
404	Image gallery does not exist.
500	Internal server error.

data field

Field Name	Type	Description
`results`	list[object]	Search results sorted by similarity score (descending). Empty list if no matches.
`results[].image_id`	string	Unique image identifier.
`results[].image_uri`	string	Image resource identifier (value provided at import).
`results[].image_base64`	string / null	Base64-encoded image content. `null` if `return_frame=false` or the image is not stored in the gallery.
`results[].score`	float	Similarity score (0 to 1). Higher values indicate greater similarity.
`results[].tags`	object	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": "red",
          "season": "summer"
        }
      },
      {
        "image_id": "img002",
        "image_uri": "https://example.com/tops/img002.jpg",
        "image_base64": "/9j/4AAQSkZJRgABAQAAAQABAAD...",
        "score": 0.891,
        "tags": {
          "color": "red",
          "season": "summer"
        }
      }
    ]
  }
}

Response example (no results)

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

2. Text-to-Image Search

Request method: POST

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

Description: Retrieve semantically matching images from a specified image gallery using a text description as input.

Supports multilingual input. In Chinese mainland deployments, the server translates input text into Chinese before searching.

Note: Only available for image galleries in general_search mode. Other modes return HTTP 400.

Request Parameters

Parameter	Type	Required	Default	Description
`library_name`	string	Yes	None	Target image gallery name. Must be in `general_search` mode.
`query_text`	string	Yes	None	Search query text, such as `white short-sleeve T-shirt` or `a white short-sleeve T-shirt`.
`top_k`	int	No	`10`	Maximum number of results to return.
`tag_filter`	list [object]	No	None	Tag-based filter conditions. Uses the tag_filter filtering syntax.
`return_frame`	bool	No	`true`	Include Base64-encoded image content in the response. Set to `false` to reduce data transfer.

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	Search succeeded (results may be an empty list).
400	Invalid request parameters or unsupported gallery mode (not general_search).
404	Image gallery does not exist.
500	Internal server error.

The data field structure is identical to search by image above.

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": {
          "category": "pants",
          "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

Filter search results by tags using the tag_filter parameter. tag_filter supports exact match and numeric range filtering. Multiple conditions are combined with AND logic.

Condition Object

Each condition is a JSON object:

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

Field	Type	Required	Default	Description
`field`	string	Yes	None	Tag field name.
`op`	string	Yes	None	Comparison operator.
`value`	string / number	Yes	None	Value to match. Strings use exact match; numbers support exact match and range filtering.

Operators

op	Meaning	Value Type	Example
`=`	Exact match	string/number	`{"field": "color", "op": "=", "value": "red"}`
`>`	Greater than	number	`{"field": "score", "op": ">", "value": 0.5}`
`>=`	Greater than or equal to	number	`{"field": "score", "op": ">=", "value": 0.9}`
`<`	Less than	number	`{"field": "score", "op": "<", "value": 1.0}`
`<=`	Less than or equal to	number	`{"field": "score", "op": "<=", "value": 0.95}`

Logical Combination

tag_filter is a JSON array. All conditions are combined with AND logic — every condition must be satisfied.

Examples

Multiple conditions combined with AND

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

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

E-commerce scenario example (filter by category + color + price range)

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

Meaning: category = "T-shirt" AND color = "white" AND price >= 50 AND price <= 200