以图搜同款图片提交接口

调用整体流程

1. 提交图片 （/v3/api/open/ai-search/image/submit或/v3/api/open/ai-search/image/submit/image-url）（本接口）
   ↓
2. 等待10-20秒
   ↓
3. 查询处理状态（/v3/api/open/ai-search/image/status）
   ↓
4. 获取结果摘要（/v3/api/open/ai-search/image/resultSummary）
   ↓
5. 根据摘要数据，选择性调用详细列表接口：
    - 产品列表：/v3/api/open/ai-search/image/product/search
    - 广告列表：/v3/api/open/ai-search/image/search4/ad/search
    - 店铺列表：/v3/api/open/ai-search/image/root-path/search
    - TikTok产品：/v3/api/open/ai-search/image/tiktok-product/search
    - TikTok店铺：/v3/api/open/ai-search/image/tiktok-shop/search

接口概述

以图搜同款功能提供两种图片提交方式：

1. 上传图片文件：直接上传本地图片文件进行搜索
2. 提交图片URL：通过图片URL地址进行搜索

两种方式都会对图片进行向量化分析，并在海量广告、产品、店铺数据中查找相似内容，返回图片ID用于后续查询搜索结果。

接口一：上传图片文件

接口信息

• 接口名称: 上传图片文件进行以图搜同款
• 请求方法: POST
• 接口地址: /open-api/v1/upload-file
• 接口路径: /v3/api/open/ai-search/image/submit
• 接口描述: 上传本地图片文件进行以图搜同款，适用于需要上传本地图片的场景
• 价格说明: 免费

请求头:

• Content-Type: multipart/form-data
• Accept: application/json

请求参数

Multipart 表单字段

将以下三个字段直接放入 multipart/form-data 表单，不使用 JSON params 对象。使用 cURL -F 或 FormData 时，让客户端自动生成带 boundary 的 Content-Type 请求头。

请求示例

使用 cURL

curl -X POST "https://www.pipispy.com/open-api/v1/upload-file" \
  -H "Accept: application/json" \
    -F "image_data=@/path/to/image.jpg" \
    -F "key=your_api_key" \
    -F "uri=/v3/api/open/ai-search/image/submit"

使用 Java（Spring RestTemplate）

import org.springframework.core.io.FileSystemResource;
import org.springframework.http.*;
import org.springframework.util.LinkedMultiValueMap;
import org.springframework.util.MultiValueMap;
import org.springframework.web.client.RestTemplate;

import java.io.File;
import java.util.Collections;

public class UploadFileExample {

    public static void main(String[] args) {
        String url = "https://www.pipispy.com/open-api/v1/upload-file";

        // 替换为你自己的图片路径和 API key
        String imagePath = "/path/to/image.jpg";
        String apiKey = "your_api_key";
        String uriParam = "/v3/api/open/ai-search/image/submit";

        // 创建 RestTemplate 实例
        RestTemplate restTemplate = new RestTemplate();

        // 构建 multipart/form-data 请求体
        FileSystemResource resource = new FileSystemResource(new File(imagePath));
        MultiValueMap<String, Object> body = new LinkedMultiValueMap<>();
        body.add("image_data", resource);
        body.add("key", apiKey);
        body.add("uri", uriParam);

        // 设置请求头
        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.MULTIPART_FORM_DATA);
        headers.setAccept(Collections.singletonList(MediaType.APPLICATION_JSON));

        HttpEntity<MultiValueMap<String, Object>> requestEntity = new HttpEntity<>(body, headers);

        // 发送 POST 请求
        try {
            ResponseEntity<String> response = restTemplate.exchange(url, HttpMethod.POST, requestEntity, String.class);
            System.out.println("Status Code: " + response.getStatusCode());
            System.out.println("Response Body: " + response.getBody());
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Maven依赖:

<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-web</artifactId>
    <version>5.3.30</version>
</dependency>

接口二：提交图片URL

接口信息

• 接口名称: 通过图片URL进行以图搜同款
• 请求方法: POST
• 接口地址: /open-api/v1/data
• 接口路径: /v3/api/open/ai-search/image/submit/image-url
• 接口描述: 通过图片URL地址进行以图搜同款，适用于图片已在线上的场景，无需上传文件
• 价格说明: 免费

请求头:

• Content-Type: application/json
• Accept: application/json

请求参数

请求结构

请求体参数 (params 对象)

请求示例

使用 cURL

curl -X POST "https://www.pipispy.com/open-api/v1/data" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "key": "your_api_key_here",
    "uri": "/v3/api/open/ai-search/image/submit/image-url",
    "params": {
        "image_url": "https://example.com/path/to/image.jpg"
    }
  }'

使用 Java（Spring RestTemplate）

import org.springframework.http.*;
import org.springframework.web.client.RestTemplate;

import java.util.HashMap;
import java.util.Map;

public class AiSearchImageUrlSubmitSpring {

    public static void main(String[] args) {
        String url = "https://www.pipispy.com/open-api/v1/data";
        String apiKey = "your_api_key_here";
        String imageUrl = "https://example.com/path/to/image.jpg";

        RestTemplate restTemplate = new RestTemplate();

        // 设置请求头
        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.APPLICATION_JSON);
        headers.set("Accept", "application/json");

        // 构建请求体
        Map<String, Object> requestBody = new HashMap<>();
        requestBody.put("key", apiKey);
        requestBody.put("uri", "/v3/api/open/ai-search/image/submit/image-url");

        Map<String, String> params = new HashMap<>();
        params.put("image_url", imageUrl);
        requestBody.put("params", params);

        HttpEntity<Map<String, Object>> requestEntity = new HttpEntity<>(requestBody, headers);

        // 发送请求
        ResponseEntity<String> response = restTemplate.exchange(
                url,
                HttpMethod.POST,
                requestEntity,
                String.class
        );

        if (response.getStatusCode() == HttpStatus.OK) {
            System.out.println("Response: " + response.getBody());
        } else {
            System.err.println("Request failed: " + response.getStatusCode());
        }
    }
}

Maven依赖:

<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-web</artifactId>
    <version>5.3.30</version>
</dependency>

响应参数

响应体结构

两个接口的响应格式完全相同。data 是图片 ID 字符串，后续请求将它作为 image_id 传入；不要读取 data.image_id。

{
  "code": 200,
  "message": "success",
  "data": "img_1234567890123456",
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 0,
  "success": true,
  "fail": false
}

响应字段说明

响应示例

成功响应

{
  "code": 200,
  "message": "success",
  "data": "img_1737532800123456",
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 0,
  "success": true,
  "fail": false
}

错误响应示例

文件为空（仅接口一）

{
  "code": 400,
  "message": "File cannot be empty",
  "data": null,
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 0,
  "success": false,
  "fail": true
}

错误码说明

后续操作

图片提交成功后，可以使用返回的 image_id 进行以下操作：

1. 查询处理状态：调用 /v3/api/open/ai-search/image/status 接口查询图片处理状态
2. 获取搜索结果摘要：调用 /v3/api/open/ai-search/image/resultSummary 接口获取结果统计
3. 查询产品列表：调用 /v3/api/open/ai-search/image/product/search 接口获取相似产品
4. 查询广告列表：调用 /v3/api/open/ai-search/image/search4/ad/search 接口获取相似广告
5. 查询店铺列表：调用 /v3/api/open/ai-search/image/root-path/search 接口获取相关店铺
6. 查询TikTok产品：调用 /v3/api/open/ai-search/image/tiktok-product/search 接口获取TikTok小店产品
7. 查询TikTok店铺：调用 /v3/api/open/ai-search/image/tiktok-shop/search 接口获取TikTok小店

处理流程说明

图片提交后的处理流程：

1. 图片获取（约1-3秒）：
   • 接口一：系统将上传的图片保存到OSS存储
   • 接口二：系统从URL下载图片并保存到OSS存储
2. 向量提取（约2-5秒）：使用AI模型提取图片特征向量
3. 向量检索（约1-3秒）：在Milvus向量库中检索相似图片
4. 结果整理（约2-5秒）：过滤和整理搜索结果

整个流程通常在10-20秒内完成。建议提交图片后，等待几秒钟再调用状态查询接口。