Image search-AnalyticDB(AnalyticDB)-阿里云帮助中心

The image search service supports search-by-image, search-by-text, and tag-based filtering for visual search scenarios such as e-commerce product retrieval, content recommendation, and security surveillance.

Important

Image search is currently in private preview. To request access, submit a ticket or contact technical support.

Core features

Multi-mode retrieval engine

Image search offers three retrieval modes for different business scenarios. You specify the mode when creating an image library, and it cannot be changed afterward.

Mode	Applicable scenario	Core capability
Item search (`item_search`)	E-commerce product retrieval, fashion design	Automatically detects and extracts the embedding of a target object for precise item-level matching.
General search (`general_search`)	Content recommendation, image library management	Whole-image semantic embedding. Supports both search-by-image and search-by-text.
Adaptive search (`adaptive_search`)	Security surveillance, identity verification	Dual-path feature extraction: optimizes for facial features when the input is a face image, and switches to whole-image semantics otherwise.

Note: Image search automatically converts images or text into high-dimensional vectors (embeddings) during import and retrieval, and uses vector similarity for semantic matching. You do not need to call an embedding model separately.

Tag filtering

Custom tags: Attach arbitrary key-value tags (such as color, season, or category) when importing images.
Compound filter syntax: Supports exact match and range filtering on numeric fields. Multiple filter conditions are combined with AND logic.
Filter at retrieval time: Apply tag conditions on top of vector similarity search to further refine results.

Multi-library management

Create multiple image libraries with isolated data between libraries, suitable for multi-tenant SaaS scenarios.

Feature overview

Feature	Description
Image library management	Create, query, and delete image libraries. Specify a retrieval mode (item search, general search, or adaptive search) at creation time. The mode is immutable after creation.
Image import	Import images into a library. Supports single synchronous import and batch asynchronous import (via an OSS JSONL file). You can attach custom tags for filtering at retrieval time.
Image retrieval	Retrieve similar images from a library. Search by image: Use an image as the query to find visually similar images. Supports item-level precision matching or whole-image semantic matching. Search by text: Enter a text description (such as "white short-sleeve T-shirt") to retrieve semantically matching images. Supports automatic multilingual translation. Tag filtering: Apply compound filter conditions based on custom tags at retrieval time, combined with AND logic.

API overview

All APIs share the following base path: /api/v1/operators/image-search

Image library management

API	Method	Path
Create an image library	POST	`/library/create`
List image libraries	GET	`/library/list`
Delete an image library	POST	`/library/delete`

Image import

API	Method	Path
Import a single image (synchronous)	POST	`/image/add`
Batch import images (asynchronous)	POST	`/image/tasks/create`
Query batch import task status	GET	`/image/tasks/results/{task_id}`

Image retrieval

API	Method	Path
Search by image	POST	`/search/by-image`
Search by text	POST	`/search/by-text`

Common response structure

All APIs return a unified JSON structure:

{
  "status": "SUCCESS",
  "message": null,
  "data": { ... }
}

Field	Type	Description
`status`	string	Business status code. `"SUCCESS"` indicates success; other values indicate the specific error type.
`message`	string / null	Status description. `null` on success; contains the specific error message on failure.
`data`	object / null	Business data. `null` on failure. For some APIs, `data` may also be `null` on success.

Standard HTTP status codes (200, 400, 403, 404, 409, 500, etc.) classify responses at a high level. The status and message fields in the response body provide detailed business error information.

Typical use cases

E-commerce product retrieval

Build a "snap and find" feature: a customer uploads a product photo, the system identifies the main subject (such as a dress or shoes), retrieves visually similar products from the catalog, and supports filtering by color, size, or other tags.

Smart content recommendation

Personalized recommendation for content platforms: when a user views an image, the system extracts its semantic features, retrieves content with similar style or theme, and ranks results based on the user profile.

Enterprise image asset management

Manage large-scale visual assets: batch-import historical images with tags, then locate materials using text descriptions or sample images.

Limits

Item	Description
Retrieval mode	The retrieval mode cannot be changed after the library is created. To switch modes, delete the library and create a new one.
Number of libraries	A maximum of 5 image libraries can be created per instance. Contact technical support if you need more.
Search by text	Available only in libraries configured with the `general_search` mode.