Import images

API overview

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

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

1. Import a single image

Method: POST

Path: /api/v1/operators/image-search/image/add

Description: Synchronously imports a single image into an image library. Pass the image as a Base64-encoded string with an image_uri as the resource identifier. Custom tags can be included for search filtering. This API is idempotent: requests with an existing image_id and image_uri combination overwrite the existing record.

Note: image_id and image_uri form a composite primary key. A single image_id can map to multiple image_uri values. For example, photos of the same product from different angles can share one image_id but use distinct image_uri values.

Request parameters

Parameter	Type	Required	Default	Description
`library_name`	string	Yes	None	Name of the target image library.
`image_id`	string	Yes	None	Unique image identifier. Forms a composite primary key with `image_uri`. A single `image_id` can map to multiple `image_uri` values.
`image_uri`	string	Yes	None	Resource identifier for the image. Can be any path-format string, such as `image_name.jpg`.
`image_base64`	string	Yes	None	Base64-encoded image string. Omit the `data:image/...;base64,` prefix.
`tags`	object	No	`{}`	Custom key-value tags for search filtering, such as `{"color": "red", "season": "summer"}`.
`save_image`	boolean	No	`true`	Whether to store the raw Base64 data in the image library. When `true`, search results include the Base64 data. Set to `false` to reduce storage usage.

Request example

curl -X POST 'http://localhost:8000/api/v1/operators/image-search/image/add' \
  -H 'Content-Type: application/json' \
  -d '{
    "library_name": "shop_a_tops",
    "image_id": "img001",
    "image_uri": "https://example.com/images/tops/img001.jpg",
    "image_base64": "/9j/4AAQSkZJRgABAQAAAQABAAD...",
    "tags": {
      "color": "white",
      "season": "summer"
    }
  }'

Response

HTTP status codes

Status code	Description
200	Import succeeded. The `data` and `message` fields are null.
400	Invalid request parameters (for example, a required field is missing).
404	The specified image library does not exist.
500	Internal server error (for example, the embedding service is unavailable).

Response example

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

Failed response example (HTTP 404)

{
  "status": "LIBRARY_NOT_FOUND",
  "message": "Image library 'shop_a_tops' does not exist",
  "data": null
}

2. Create a batch import task

Method: POST

Path: /api/v1/operators/image-search/image/tasks/create

Description: Creates an asynchronous batch import task for an image library. Images are listed in a JSONL file stored in OSS. Returns a task ID immediately. Poll the task status API with this ID to track progress.

Batch import data format

The OSS data file must be in JSONL format: each line is a single JSON object representing one operation.

Parameter	Type	Required	Default	Description
`image_id`	string	Yes	None	Unique image identifier.
`image_uri`	string	Yes	None	Image path in OSS, relative to the meta file within the same bucket. Used by the server to download the image.
`action`	string	No	`ADD`	Operation to perform. Currently only `ADD` (add image) is supported.
`tags`	object	No	`{}`	Custom key-value tags for search filtering.

Data example

{"image_id": "img001", "image_uri": "tops/img001.jpg", "tags": {"color": "white", "season": "summer"}}
{"image_id": "img002", "image_uri": "tops/img002.jpg", "tags": {"color": "black"}}
{"image_id": "img003", "image_uri": "tops/img003.jpg"}

Request parameters

Parameter	Type	Required	Default	Description
`library_name`	string	Yes	None	Name of the target image library.
`meta_file_uri`	string	Yes	None	Path to the JSONL file in OSS. Format: `oss://bucket/path/import_task.jsonl`.
`save_image`	boolean	No	`true`	Whether to store the raw Base64 data in the image library. When `true`, search results include the Base64 data. Set to `false` to reduce storage usage.

Request example

curl -X POST 'http://localhost:8000/api/v1/operators/image-search/image/tasks/create' \
  -H 'Content-Type: application/json' \
  -d '{
    "library_name": "shop_a_tops",
    "meta_file_uri": "oss://my-bucket/batch/import_task.jsonl"
  }'

Response

HTTP status codes

Status code	Description
200	Task created and running asynchronously.
400	Invalid request parameters.
404	The specified image library does not exist.
500	Internal server error.

data field

Parameter	Type	Description
`task_id`	string	Unique task ID for polling task status.

Response example

{
  "status": "SUCCESS",
  "message": null,
  "data": {
    "task_id": "task_x9y8z7w6v5"
  }
}

3. Query task status

Method: GET

Path: /api/v1/operators/image-search/image/tasks/results/{task_id}

Description: Queries the status and progress of a batch import task. Poll this endpoint to check completion, view success and failure counts, and retrieve error details.

Path parameters

Parameter	Type	Required	Description
`task_id`	string	Yes	Task ID returned by the batch import task creation API.

Request example

curl -X GET 'http://localhost:8000/api/v1/operators/image-search/image/tasks/results/task_x9y8z7w6v5'

Response

HTTP status codes

Status code	Description
200	The query was successful.
404	The specified task ID does not exist.
500	Internal server error.

data field

Parameter	Type	Description
`task_id`	string	The ID of the task.
`task_status`	string	Task execution status. Values: `PENDING` (queued), `RUNNING` (processing), `SUCCESS` (completed; check `failed_count` for record-level errors), `FAILED` (terminated by error).
`total`	int	Total number of records in the meta file.
`processed`	int	Number of processed records.
`failed_count`	int	Number of images that failed to process.
`message`	string	Error message, typically indicating the reason for the last failed record.

Response example

{
  "status": "SUCCESS",
  "message": null,
  "data": {
    "task_id": "task_x9y8z7w6v5",
    "task_status": "SUCCESS",
    "total": 100,
    "processed": 100,
    "failed_count": 2,
    "message": "Image download failed: the OSS object does not exist"
  }
}

Failed response example (HTTP 404)

{
  "status": "TASK_NOT_FOUND",
  "message": "Task 'task_abc123' does not exist",
  "data": null
}