Pipispy APIEnglish

数据消耗规则:1. 获取一条数据结果消耗1 数据,获取数据结果的更多数据详情不消耗数据。2. 广告监控: 每次监控 $1 / 月。单个监控有效期为一个月,一个月后自动停止。删除监控不会恢复监控次数,请谨慎删除。监控调用为随时且无限次。

以图搜产品接口

调用整体流程

1. 提交图片 (/v3/api/open/ai-search/image/submit或/v3/api/open/ai-search/image/submit/image-url),得到 image_id
   ↓
2. 等待10-20秒
   ↓
3. 根据image_id查询处理状态(/v3/api/open/ai-search/image/status)
   ↓
4. 根据image_id获取结果摘要(/v3/api/open/ai-search/image/resultSummary)
   ↓
5. 根据摘要数据以及image_id,选择性调用详细列表接口:
    - 产品列表:/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

接口概述

以图搜产品接口用于根据图片搜索相似的电商产品。需要先通过图片提交接口获取 image_id,然后使用该接口查询与图片相似的产品列表。

该接口支持丰富的过滤条件,包括平台类型、数据类型、地区、关键词、互动数据范围、时间范围等多维度筛选,帮助用户精准定位目标产品。


接口信息

  • 接口名称: 以图搜产品
  • 请求方法: POST
  • 接口地址: /open-api/v1/data
  • 接口路径: /v3/api/open/ai-search/image/product/search
  • 接口描述: 根据图片ID查询相似产品,支持多维度过滤和排序
  • 价格说明: 获取一条数据结果消耗1 credit

请求头:

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

请求参数

请求结构

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

请求体参数 (params 对象)

参数名 类型 必填 描述
image_id String 是 图片ID,通过图片提交接口获得。格式:img_开头+时间戳
current_page Integer 是 当前页码,从1开始
page_size Integer 是 每页数量
plat_type Integer 否 平台类型 (0:全部, 1:tiktok, 2:facebook)
time Integer 否 时间范围 (0:全部, 1:昨天, 7:近7天, 30:近30天, 90:近90天)
keyword String 否 搜索关键词
search_type Integer 否 搜索类型 (1:产品标题, 2:产品描述, 3:广告主URL, 4:广告主名, 5:产品关键词)
category String 否 产品分类ID列表,见 电商分类,使用逗号分隔多个分类ID
region String 否 地区列表,支持GB/US等地区代码,见 国家地区,使用逗号分隔多个地区
play_count_min Integer 否 最小广告播放数
play_count_max Integer 否 最大广告播放数
digg_count_min Integer 否 最小点赞数
digg_count_max Integer 否 最大点赞数
digg_play_rate_min Double 否 最小点赞率
digg_play_rate_max Double 否 最大点赞率
comment_count_min Integer 否 最小评论数
comment_count_max Integer 否 最大评论数
share_count_min Integer 否 最小分享数
share_count_max Integer 否 最大分享数
video_count_min Integer 否 最小广告数量
video_count_max Integer 否 最大广告数量
put_day_min Integer 否 最小投放天数
put_day_max Integer 否 最大投放天数
create_time_start Integer 否 产品创建时间起始值(Unix时间戳,秒)
create_time_end Integer 否 产品创建时间结束值(Unix时间戳,秒)
tiktok_time_start Integer 否 广告开始日期,首次发现时间起始值(Unix时间戳,秒),需注意,这里并不是只指tiktok广告开始时间,前缀“tiktok”仅为命名习惯,无实际区分意义,也就是说当仅plat_type=2时,指的就是facebook广告开始时间,当plat_type=0,代表的是全部广告开始时间
tiktok_time_end Integer 否 广告开始日期,首次发现时间结束值(Unix时间戳,秒),需注意,这里并不是只指tiktok广告开始时间结束值,前缀“tiktok”仅为命名习惯,无实际区分意义,也就是说当仅plat_type=2时,指的就是facebook广告开始时间结束值,当plat_type=0,代表的是全部广告开始时间结束值
latest_found_time_start Integer 否 广告结束日期,最新发现时间起始值(Unix时间戳,秒)
latest_found_time_end Integer 否 广告结束日期,最新发现时间结束值(Unix时间戳,秒)
price_min Double 否 产品价格(USD),最小价格
price_max Double 否 产品价格(USD),最大价格
currency String 否 货币单位,使用逗号分隔多个货币
platform String 否 平台标识,使用逗号分隔,支持:shopify、woocommerce、shoplazza、magento、wix、shopline、squarespace、shopyy
popular_person_count_min Integer 否 最小红人数量(仅plat_type=1时有效)
popular_person_count_max Integer 否 最大红人数量(仅plat_type=1时有效)
root_path String 否 广告主名
id String 否 产品ID,使用逗号分隔多个ID
store_id String 否 店铺唯一标识ID,为13位字符串(例如:c2d5b2547218a),对应店铺榜单列表接口返回结果中的store_id字段
after_id String 否 分页游标ID(用于深度分页)
after_key String 否 分页游标键值(用于深度分页)
sort Integer 否 排序方式:
当plat_type=0时
9-按相似度排序(默认)
0-总开始日期
1-总结束日期
2-产品创建时间
3-产品价格(USD)
4-总广告数
5-广告播放
6-总点赞数
7-投放天数

当plat_type=1时
9-按相似度排序(默认)
0-tiktok广告开始时间
1-tiktok广告结束时间
2-tiktok产品创建时间
3-tiktok产品价格(USD)
4-tiktok广告数
5-tiktok播放数
6-tiktok点赞数
7-tiktok投放天数
8-tiktok红人数

当plat_type=2时
9-按相似度排序(默认)
0-facebook广告开始时间
1-facebook广告结束时间
2-facebook产品创建时间
3-facebook产品价格(USD)
4-facebook广告数
5-facebook播放数
6-facebook点赞数
7-facebook投放天数
sort_type String 否 排序类型 (asc:升序, desc:降序)

请求示例

基础请求示例

使用 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/product/search",
    "params": {
        "image_id": "img_1737532800123456",
        "current_page": 1,
        "page_size": 20
    }
  }'

高级过滤示例

使用关键词和地区过滤

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/product/search",
    "params": {
        "image_id": "img_1737532800123456",
        "current_page": 1,
        "page_size": 20,
        "plat_type": 1,
        "region": "US,GB",
        "keyword": "fashion",
        "search_type": 2,
        "play_count_min": 10000,
        "sort": 0,
        "sort_type": "desc"
    }
  }'

按价格范围和分类过滤

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/product/search",
    "params": {
        "image_id": "img_1737532800123456",
        "current_page": 1,
        "page_size": 20,
        "price_min": 10,
        "price_max": 100,
        "category": "62739afc38365b2f72048ebe",
        "time": 30,
        "sort": 9
    }
  }'

响应参数

响应体结构

{
  "code": 200,
  "message": "success",
  "data": {
    "data": [ ... ],
    "page": { ... }
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 20,
  "success": true,
  "fail": false
}

响应字段说明

顶层字段

字段名 类型 描述
code Integer 响应状态码,200 表示成功
message String 响应消息
data Object 响应数据,包含 data(产品列表)和 page(分页信息)
version String API 版本
timestamp String 响应时间戳
sign String 响应签名
remaining_credits Long 当前请求后的剩余可用积分
consumed_credits Long 本次请求消耗的积分
success Boolean 请求是否成功
fail Boolean 请求是否失败

产品数据字段 (data)

字段名 类型 描述
id String 产品唯一标识ID
title String 产品标题
image String 产品主图片URL
price Double 产品价格
currency String 产品价格货币类型
usd_price Double 产品美元价格
platform String 产品平台标识
is_collection Boolean 是否已收藏
create_time Long 产品创建时间戳
tiktok_time Long TikTok平台首次发现时间戳
found_time Long TikTok平台首次发现时间戳
latest_found_time Long TikTok平台最新发现时间戳
play_count Long TikTok平台播放量
digg_count Long TikTok平台点赞数
digg_play_rate Double TikTok平台点赞播放比
comment_count Long TikTok平台评论数
share_count Long TikTok平台分享数
video_count Long TikTok平台视频数量
put_days Long TikTok平台投放天数
ad_platform_list List<String> 广告平台列表(如:tiktok, facebook)
popular_person_count Long 达人数量
facebook_data_count Long Facebook平台数据数量
facebook_digg_count Long Facebook平台点赞数
facebook_found_time Long Facebook平台首次发现时间戳
facebook_latest_found_time Long Facebook平台最新发现时间戳
facebook_put_days Long Facebook平台投放天数
facebook_share_count Long Facebook平台分享数
facebook_comment_count Long Facebook平台评论数
all_data_count Long 全平台数据数量
all_digg_count Long 全平台点赞数
all_found_time Long 全平台首次发现时间戳
all_latest_found_time Long 全平台最新发现时间戳
all_put_days Long 全平台投放天数
all_share_count Long 全平台分享数
all_comment_count Long 全平台评论数
sort_id String 排序ID(用于分页排序)

分页信息字段 (page)

字段名 类型 描述
total_count Long 总记录数
page_count Long 总页数
current_page Long 当前页码
page_size Long 每页大小
is_next Boolean 是否有下一页

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "data": [
      {
        "id": "product_001",
        "title": "Wireless Bluetooth Headphones",
        "image": "https://cdn-product.pipispy.com/product_001.jpg",
        "price": 29.99,
        "currency": "USD",
        "usd_price": 29.99,
        "platform": "shopify",
        "is_collection": false,
        "create_time": 1700000000,
        "tiktok_time": 1700086400,
        "found_time": 1700086400,
        "latest_found_time": 1737532800,
        "play_count": 1523456,
        "digg_count": 45678,
        "digg_play_rate": 0.03,
        "comment_count": 3456,
        "share_count": 1234,
        "video_count": 125,
        "put_days": 45,
        "ad_platform_list": ["tiktok", "facebook"],
        "popular_person_count": 23,
        "facebook_data_count": 56,
        "facebook_digg_count": 12345,
        "facebook_found_time": 1700172800,
        "facebook_latest_found_time": 1737446400,
        "facebook_put_days": 38,
        "facebook_share_count": 567,
        "facebook_comment_count": 890,
        "all_data_count": 181,
        "all_digg_count": 58023,
        "all_found_time": 1700086400,
        "all_latest_found_time": 1737532800,
        "all_put_days": 45,
        "all_share_count": 1801,
        "all_comment_count": 4346,
        "sort_id": "product_001"
      },
      {
        "id": "product_002",
        "title": "Smart Watch Fitness Tracker",
        "image": "https://cdn-product.pipispy.com/product_002.jpg",
        "price": 49.99,
        "currency": "USD",
        "usd_price": 49.99,
        "platform": "shopify",
        "is_collection": true,
        "create_time": 1699913600,
        "tiktok_time": 1700000000,
        "found_time": 1700000000,
        "latest_found_time": 1737446400,
        "play_count": 2345678,
        "digg_count": 78901,
        "digg_play_rate": 0.034,
        "comment_count": 5678,
        "share_count": 2345,
        "video_count": 198,
        "put_days": 52,
        "ad_platform_list": ["tiktok"],
        "popular_person_count": 45,
        "facebook_data_count": 0,
        "facebook_digg_count": 0,
        "facebook_found_time": 0,
        "facebook_latest_found_time": 0,
        "facebook_put_days": 0,
        "facebook_share_count": 0,
        "facebook_comment_count": 0,
        "all_data_count": 198,
        "all_digg_count": 78901,
        "all_found_time": 1700000000,
        "all_latest_found_time": 1737446400,
        "all_put_days": 52,
        "all_share_count": 2345,
        "all_comment_count": 5678,
        "sort_id": "product_002"
      }
    ],
    "page": {
      "total_count": 1000,
      "page_count": 50,
      "current_page": 1,
      "page_size": 20,
      "is_next": true
    }
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 20,
  "success": true,
  "fail": false
}

错误码说明

错误码 描述
200 成功
400 请求参数错误
401 未授权 - API 密钥无效
500 服务器内部错误

相关接口

完整的以图搜产品流程涉及以下接口:

  1. 图片提交: /v3/api/open/ai-search/image/submit 或 /v3/api/open/ai-search/image/submit/image-url
  2. 处理状态查询: /v3/api/open/ai-search/image/status
  3. 结果摘要: /v3/api/open/ai-search/image/resultSummary
  4. 广告搜索: /v3/api/open/ai-search/image/search4/ad/search
  5. 产品搜索(本接口): /v3/api/open/ai-search/image/product/search
  6. 店铺搜索: /v3/api/open/ai-search/image/root-path/search
  7. TikTok产品搜索: /v3/api/open/ai-search/image/tiktok-product/search
  8. TikTok店铺搜索: /v3/api/open/ai-search/image/tiktok-shop/search

使用说明

  1. 相似度排序: 默认情况下(sort=9),产品列表按图片相似度降序排列,最相似的产品排在最前面
  2. 平台筛选: 使用 plat_type 参数可以筛选特定平台的产品数据
  3. 时间范围: 使用 time 参数可以获取指定时间范围内的产品数据
  4. 关键词搜索: 支持多种搜索类型,可按产品标题、描述、店铺URL等不同维度搜索
  5. 地区过滤: 支持多地区筛选,使用逗号分隔多个地区代码
  6. 分类过滤: 支持按产品分类筛选,需要使用正确的分类ID
  7. 数据统计: 返回结果包含 TikTok、Facebook 和全平台的完整统计数据