通过API单张或批量导入图片-云原生数据仓库AnalyticDB(AnalyticDB)-阿里云帮助中心

图片导入 API 用于将图片导入到图片库。支持单张同步导入和批量异步导入（通过 OSS JSONL 文件），导入时可附带自定义标签。

接口总览

说明：所有接口统一前缀为 /api/v1/operators/image-search。

接口名称	方法	路径
向图片库导入单张图片（同步接口）	POST	`/api/v1/operators/image-search/image/add`
向图片库批量导入（异步接口）	POST	`/api/v1/operators/image-search/image/tasks/create`
查询批量导入任务状态	GET	`/api/v1/operators/image-search/image/tasks/results/{task_id}`

1. 导入单张图片（同步接口）

请求方法：POST

请求路径：/api/v1/operators/image-search/image/add

接口说明：向指定图片库同步导入单张图片。图片内容通过 Base64 编码传入，同时需提供 image_uri 作为资源标识。导入时可附带自定义标签，用于后续检索过滤。支持幂等写入：相同 image_id + image_uri 组合会覆盖更新已有记录。

说明：image_id 和 image_uri 共同构成唯一标识。一个 image_id 可对应多个 image_uri，例如同一商品的多角度照片可共享 image_id，通过不同 image_uri 区分。

请求参数

参数名	类型	是否必选	默认值	参数含义
`library_name`	string	是	无	目标图片库名称。
`image_id`	string	是	无	图片唯一标识，与 `image_uri` 共同组成复合主键。一个 `image_id` 可对应多个 `image_uri`。
`image_uri`	string	是	无	图片资源标识，可为任意格式的路径字符串（如 `image_name.jpg`）。
`image_base64`	string	是	无	图片的 Base64 编码字符串，不含 `data:image/...;base64,` 前缀。
`tags`	object	否	`{}`	用户自定义标签键值对，如 `{"color": "red", "season": "summer"}`，可用于检索时的标签过滤。
`save_image`	boolean	否	`true`	是否在图片库中保存图片 Base64 原始数据。保存后，检索结果中将返回图片的 Base64 数据；设为 `false` 可节省存储空间。

请求示例

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"
    }
  }'

响应说明

HTTP 状态码

状态码	含义
200	导入成功，响应体中 data 和 message 均为 null。
400	请求参数错误（如缺少必填字段）。
404	图片库不存在。
500	服务器内部错误（如 embedding 服务异常）。

响应示例

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

失败响应示例（HTTP 404）

{
  "status": "LIBRARY_NOT_FOUND",
  "message": "图片库 'shop_a_tops' 不存在",
  "data": null
}

2. 创建批量导入任务（异步）

请求方法：POST

请求路径：/api/v1/operators/image-search/image/tasks/create

接口说明：创建一个异步批量导入任务，批量导入图片到指定图片库。通过引用 OSS 上的 JSON 文件提供待导入的图片列表。接口立即返回任务 ID，可通过任务状态查询接口轮询进度。

批量导入数据格式

OSS 上的 meta 文件为 JSONL 格式，每个元素为一条操作记录，必须保证每一个元素为一行：

字段名	类型	是否必选	默认值	字段含义
`image_id`	string	是	无	图片唯一标识。
`image_uri`	string	是	无	图片在 OSS 上相对于 meta 文件同 bucket 下的路径，服务端据此下载图片。
`action`	string	否	`ADD`	操作类型（`ADD`：添加图片）。
`tags`	object	否	`{}`	用户自定义标签键值对，可用于检索时的标签过滤。

数据示例

{"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"}

请求参数

参数名	类型	是否必选	默认值	参数含义
`library_name`	string	是	无	目标图片库名称。
`meta_file_uri`	string	是	无	OSS 上的 JSON 文件路径，格式如 `oss://bucket/path/import_task.jsonl`。
`save_image`	boolean	否	`true`	是否在图片库中保存图片 Base64 原始数据。保存后，检索结果中将返回图片的 Base64 数据。

请求示例

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.json"
  }'

响应说明

HTTP 状态码

状态码	含义
200	任务创建成功（异步执行中）。
400	请求参数错误。
404	图片库不存在。
500	服务器内部错误。

data 字段

字段名	类型	说明
`task_id`	string	任务唯一 ID，用于轮询任务状态。

响应示例

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

3. 查询任务状态

请求方法：GET

请求路径：/api/v1/operators/image-search/image/tasks/results/{task_id}

接口说明：查询批量导入任务的执行状态和进度。通过轮询该接口获知任务是否完成、成功/失败数量和错误详情。

路径参数

参数名	类型	是否必选	参数含义
`task_id`	string	是	任务创建接口返回的任务 ID。

请求示例

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

响应说明

HTTP 状态码

状态码	含义
200	查询成功。
404	任务 ID 不存在。
500	服务器内部错误。

data 字段

字段名	类型	说明
`task_id`	string	任务 ID。
`task_status`	string	任务执行状态：`PENDING`（等待中）、`RUNNING`（执行中）、`SUCCESS`（全部成功）、`FAILED`（全部失败）。
`total`	int	meta 文件中的总记录数。
`processed`	int	已处理的记录数。
`failed_count`	int	处理失败的图片数量。
`message`	string	失败信息（最后一条失败记录的原因）。

响应示例

{
  "status": "SUCCESS",
  "message": null,
  "data": {
    "task_id": "task_x9y8z7w6v5",
    "task_status": "SUCCESS",
    "total": 100,
    "processed": 100,
    "failed_count": 2,
    "message": "图片下载失败：OSS 对象不存在"
  }
}

失败响应示例（HTTP 404）

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