Pipispy APIEnglish

以图搜同款状态查询接口

调用整体流程

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

接口信息

  • 接口名称: 查询图片处理状态
  • 请求方法: GET
  • 接口地址: /open-api/v1/data
  • 接口路径: /v3/api/open/ai-search/image/status
  • 接口描述: 查询图片处理的当前状态，用于判断图片是否处理完成。建议在图片提交后定期轮询此接口，直到状态变为 SEARCH_COMPLETED
  • 价格说明: 免费

请求头:

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

请求参数

请求结构

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

请求体参数 (params 对象)

参数名 类型 必填 描述
image_id
String
是
图片唯一标识ID，通过图片提交接口（/v3/api/open/ai-search/image/submit 或 /v3/api/open/ai-search/image/submit/image-url）返回获得。格式：img_开头+时间戳

请求示例

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

响应参数

响应体结构

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

响应字段说明

字段名 类型 描述
code
Integer
响应状态码，200 表示成功
message
String
响应消息
data
String
图片处理状态，见状态值说明
version
String
API 版本
timestamp
String
响应时间戳
sign
String
响应签名
remaining_credits
Long
当前请求后的剩余可用积分
consumed_credits
Long
本次请求消耗的积分
success
Boolean
请求是否成功
fail
Boolean
请求是否失败

状态值说明

状态值 说明 是否可查询结果 建议操作
UPLOAD_COMPLETED
图片上传完成，正在进行向量提取
否
继续轮询，等待向量提取完成
ANALYSIS_COMPLETED
向量提取完成，正在进行向量检索
否
继续轮询，等待检索完成
SEARCH_COMPLETED
搜索完成，所有处理已完成
是
可以调用结果摘要和详细列表接口获取搜索结果
ANALYSIS_FAILURE
向量提取失败
否
可能是图片内容无法识别，尝试更换图片
SEARCH_FAILURE
向量检索失败
否
系统错误，请联系技术支持

响应示例

处理完成

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

错误码说明

错误码 描述
200
成功
400
请求参数错误（image_id缺失、图片记录不存在等）
401
未授权（API Key无效或过期）
500
服务器内部错误

使用场景

此接口主要用于以下场景：

  1. 轮询图片处理进度：在用户提交图片后，定期查询处理状态，实时展示处理进度
  2. 判断是否可查询结果：确认状态为 SEARCH_COMPLETED 后，再调用结果摘要和详细列表接口
  3. 错误处理：及时发现处理失败，给用户相应提示
  4. 用户体验优化：在UI上展示处理进度条或状态提示

典型使用流程

1. 提交图片
   ↓
2. 等待3-5秒后开始轮询状态
   ↓
3. 调用状态接口
   ├─ 如果状态为 UPLOAD_COMPLETED/ANALYSIS_COMPLETED
   │  └─ 等待2-3秒后继续轮询
   ├─ 如果状态为 SEARCH_COMPLETED
   │  └─ 进入步骤4
   └─ 如果状态为 *_FAILURE
      └─ 处理失败，检查错误原因
   ↓
4. 调用结果摘要接口获取搜索结果统计
   ↓
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