Image Search - Image Submission API

Overall Call Flow

1. Submit image (/v3/api/open/ai-search/image/submit or /v3/api/open/ai-search/image/submit/image-url) (This API)
   ↓
2. Wait 10-20 seconds
   ↓
3. Query processing status (/v3/api/open/ai-search/image/status)
   ↓
4. Get result summary (/v3/api/open/ai-search/image/resultSummary)
   ↓
5. Based on summary data, selectively call detailed list APIs:
    - Product list: /v3/api/open/ai-search/image/product/search
    - Ad list: /v3/api/open/ai-search/image/search4/ad/search
    - Store list: /v3/api/open/ai-search/image/root-path/search
    - TikTok products: /v3/api/open/ai-search/image/tiktok-product/search
    - TikTok shops: /v3/api/open/ai-search/image/tiktok-shop/search

API Overview

The image search feature provides two image submission methods:

1. Upload Image File: Directly upload local image files for search
2. Submit Image URL: Search using an image URL address

Both methods will vectorize the image and search for similar content in massive ad, product, and store data, returning an image ID for subsequent result queries.

API 1: Upload Image File

API Information

• API Name: Upload Image File for Image Search
• Request Method: POST
• API Address: /open-api/v1/upload-file
• API Path: /v3/api/open/ai-search/image/submit
• API Description: Upload local image files for image search, suitable for scenarios requiring local image uploads
• Pricing: Free

Request Headers:

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

Request Parameters

Multipart Form Fields

Send these three fields directly in a multipart/form-data body, without a JSON params object. When using cURL -F or FormData, let the client generate the Content-Type header with its multipart boundary.

Request Examples

Using 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"

Using 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";

        // Replace with your own image path and API key.
        String imagePath = "/path/to/image.jpg";
        String apiKey = "your_api_key";
        String uriParam = "/v3/api/open/ai-search/image/submit";

        // Create a RestTemplate instance.
        RestTemplate restTemplate = new RestTemplate();

        // Build a multipart/form-data request body.
        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);

        // Set the request headers.
        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);

        // Send a POST request.
        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:

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

API 2: Submit Image URL

API Information

• API Name: Image Search via Image URL
• Request Method: POST
• API Address: /open-api/v1/data
• API Path: /v3/api/open/ai-search/image/submit/image-url
• API Description: Search via image URL address, suitable for scenarios where images are already online, no file upload needed
• Pricing: Free

Request Headers:

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

Request Parameters

Request Structure

Request Body Parameters (params object)

Request Examples

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

Using 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();

        // Set request headers
        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.APPLICATION_JSON);
        headers.set("Accept", "application/json");

        // Build request body
        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);

        // Send request
        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:

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

Response Parameters

Response Body Structure

Both APIs have the same response format. data is the image ID string. Pass it as image_id in subsequent requests; do not read 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
}

Response Field Description

Response Examples

Success Response

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

Error Response Examples

Empty File (API 1 only)

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

Error Code Description

Next Steps

After successful image submission, you can use the returned image_id for the following operations:

1. Query Processing Status: Call /v3/api/open/ai-search/image/status API to query image processing status
2. Get Search Result Summary: Call /v3/api/open/ai-search/image/resultSummary API to get result statistics
3. Query Product List: Call /v3/api/open/ai-search/image/product/search API to get similar products
4. Query Ad List: Call /v3/api/open/ai-search/image/search4/ad/search API to get similar ads
5. Query Store List: Call /v3/api/open/ai-search/image/root-path/search API to get related stores
6. Query TikTok Products: Call /v3/api/open/ai-search/image/tiktok-product/search API to get TikTok Shop products
7. Query TikTok Shops: Call /v3/api/open/ai-search/image/tiktok-shop/search API to get TikTok Shops

Processing Flow Description

Processing flow after image submission:

1. Image Acquisition (approx. 1-3 seconds):
   • API 1: System saves uploaded image to OSS storage
   • API 2: System downloads image from URL and saves to OSS storage
2. Vector Extraction (approx. 2-5 seconds): Use AI model to extract image feature vectors
3. Vector Retrieval (approx. 1-3 seconds): Search for similar images in Milvus vector database
4. Result Organization (approx. 2-5 seconds): Filter and organize search results

The entire process typically completes within 10-20 seconds. It's recommended to wait a few seconds after submitting the image before calling the status query API.