# 以图搜同款图片提交接口
## 调用整体流程
```
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 请求头。

| 参数名 | 类型 | 必填 | 描述 |
| --- | --- | --- | --- |
| key | string | 是 | 用户申请的 API Key。 |
| uri | string | 是 | 固定为 `/v3/api/open/ai-search/image/submit`。 |
| image_data | File | 是 | 本地图片文件。支持 jpg、jpeg、png、gif、bmp、webp；建议不超过 10MB、4096×4096 像素。 |

### 请求示例

#### 使用 cURL

```bash
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）

```java
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依赖:**
```xml
<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

### 请求参数

#### 请求结构

| 参数名 | 类型   | 描述                        | 示例                                           | 必填 | 默认值 |
| ------ | ------ | --------------------------- | ---------------------------------------------- | ---- | ------ |
| key    | string | 用户申请的外部 api 请求 key | "your_api_key_here"                            | 是   |        |
| uri    | string | 接口路径                    | "/v3/api/open/ai-search/image/submit/image-url" | 是   |        |
| params | object | 接口入参对象                | 见参数列表                                     | 是   |        |

#### 请求体参数 (params 对象)

| 参数名    | 类型   | 必填 | 描述                                                                                                                                                                                                                                 |
| --------- | ------ | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| image_url | String | 是   | 图片的URL地址。必须是可公开访问的HTTP/HTTPS链接。支持的图片格式：jpg、jpeg、png、gif、bmp、webp。建议图片大小不超过10MB，尺寸不超过4096x4096像素。系统会下载该图片并转换为向量进行相似度匹配                                        |

### 请求示例

#### 使用 cURL

```bash
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）

```java
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依赖:**
```xml
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-web</artifactId>
    <version>5.3.30</version>
</dependency>
```

---

## 响应参数

### 响应体结构

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

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

### 响应字段说明

| 字段名          | 类型    | 描述                                                    |
| --------------- | ------- |-------------------------------------------------------|
| code            | Integer | 响应状态码，200 表示成功                                        |
| message         | String  | 响应消息                                                  |
| data            | String  | 响应数据, 图片唯一标识ID, 即image_id，用于后续查询搜索状态和结果。格式：img_开头+时间戳 |
| version         | String  | API 版本                                                |
| timestamp       | String  | 响应时间戳                                                 |
| sign            | String  | 响应签名                                                  |
| remaining_credits | Long    | 当前请求后的剩余可用积分 |
| consumed_credits  | Long    | 本次请求消耗的积分 |
| success         | Boolean | 请求是否成功                                                |
| fail            | Boolean | 请求是否失败                                                |

## 响应示例

### 成功响应

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

### 错误响应示例

#### 文件为空（仅接口一）

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

## 错误码说明

| 错误码 | 描述                                                       |
| ------ | ---------------------------------------------------------- |
| 200    | 成功                                                       |
| 400    | 请求参数错误（文件为空、文件名无效、文件格式不支持、URL无效等） |
| 401    | 未授权（API Key无效或过期）                                |
| 500    | 服务器内部错误（图片上传失败、向量化处理失败等）           |

## 后续操作

图片提交成功后，可以使用返回的 `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秒内完成。建议提交图片后，等待几秒钟再调用状态查询接口。