Pipispy API中文

Data usage rules: 1. Obtaining a data result consumes 1 data. Obtaining more detailed information about a data result does not consume data. 2. Ad Tracker: Each monitoring session costs $1/month. Each monitoring session is valid for one month and automatically expires after one month. Deleting a monitoring session does not restore the monitoring session, so please delete with caution. Monitoring sessions can be accessed at any time and are unlimited.

Image Search - Status Query API

Overall Call Flow

1. Submit image (/v3/api/open/ai-search/image/submit or /v3/api/open/ai-search/image/submit/image-url)
   ↓
2. Wait 10-20 seconds
   ↓
3. Query processing status (/v3/api/open/ai-search/image/status) (This API)
   ↓
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 Information

  • API Name: Query Image Processing Status
  • Request Method: GET
  • API Address: /open-api/v1/data
  • API Path: /v3/api/open/ai-search/image/status
  • API Description: Query the current processing status of an image to determine if processing is complete. It's recommended to poll this API periodically after image submission until the status becomes SEARCH_COMPLETED
  • Pricing: Free

Request Headers:

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

Request Parameters

Request Structure

Parameter Type Description Example Required Default
key string User's external API request key "your_api_key_here" Yes
uri string API path "/v3/api/open/ai-search/image/status" Yes
params object API input parameters See parameter list Yes

Request Body Parameters (params object)

Parameter Type Required Description
image_id String Yes Image unique identifier ID, obtained from image submission API (/v3/api/open/ai-search/image/submit or /v3/api/open/ai-search/image/submit/image-url). Format: img_ prefix + timestamp

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/status",
    "params": {
        "image_id": "img_1737532800123456"
    }
  }'

Response Parameters

Response Body Structure

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

Response Field Description

Field Name Type Description
code Integer Response status code, 200 indicates success
message String Response message
data String Image processing status, see status values
version String API version
timestamp String Response timestamp
sign String Response signature
remaining_credits Long Current remaining available credits after this request
consumed_credits Long Credits consumed by this request
success Boolean Whether request succeeded
fail Boolean Whether request failed

Status Value Description

Status Value Description Can Query Results Recommended Action
UPLOAD_COMPLETED Image upload complete, vector extraction in progress No Continue polling, wait for vector extraction
ANALYSIS_COMPLETED Vector extraction complete, vector retrieval in progress No Continue polling, wait for retrieval completion
SEARCH_COMPLETED Search complete, all processing finished Yes Can call result summary and detailed list APIs
ANALYSIS_FAILURE Vector extraction failed No Image content may be unrecognizable, try another
SEARCH_FAILURE Vector retrieval failed No System error, please contact technical support

Response Examples

Processing Complete

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

Error Code Description

Error Code Description
200 Success
400 Request parameter error (missing image_id, image record not found, etc.)
401 Unauthorized (invalid or expired API Key)
500 Internal server error

Use Cases

This API is mainly used for the following scenarios:

  1. Poll Image Processing Progress: After user submits image, periodically query processing status to display real-time progress
  2. Determine if Results Can Be Queried: After confirming status is SEARCH_COMPLETED, call result summary and detailed list APIs
  3. Error Handling: Promptly detect processing failures and provide appropriate user prompts
  4. User Experience Optimization: Display progress bar or status prompts in UI

Typical Usage Flow

1. Submit image
   ↓
2. Wait 3-5 seconds before starting to poll status
   ↓
3. Call status API
   ├─ If status is UPLOAD_COMPLETED/ANALYSIS_COMPLETED
   │  └─ Wait 2-3 seconds and continue polling
   ├─ If status is SEARCH_COMPLETED
   │  └─ Proceed to step 4
   └─ If status is *_FAILURE
      └─ Handle failure, check error reason
   ↓
4. Call result summary API to get search result statistics
   ↓
5. Call detailed list APIs as needed:
   - 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