数据消耗规则:1. 获取一条数据结果消耗1 数据,获取数据结果的更多数据详情不消耗数据。2. 广告监控: 每次监控 $1 / 月。单个监控有效期为一个月,一个月后自动停止。删除监控不会恢复监控次数,请谨慎删除。监控调用为随时且无限次。
以图搜同款状态查询接口
调用整体流程
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 |
服务器内部错误 |
使用场景
此接口主要用于以下场景:
- 轮询图片处理进度:在用户提交图片后,定期查询处理状态,实时展示处理进度
- 判断是否可查询结果:确认状态为 SEARCH_COMPLETED 后,再调用结果摘要和详细列表接口
- 错误处理:及时发现处理失败,给用户相应提示
- 用户体验优化:在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