以图搜TikTok店铺接口
调用整体流程
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(本接口)
接口概述
以图搜TikTok店铺接口用于根据图片搜索相似的TikTok Shop店铺。需要先通过图片提交接口获取 image_id,然后使用该接口查询与图片相似的TikTok店铺列表。
该接口支持丰富的过滤条件,包括关键词搜索、地区、分类、销量、价格、广告数据等多维度筛选,帮助用户精准定位目标店铺。
接口信息
- 接口名称: 以图搜TikTok店铺
- 请求方法: POST
- 接口地址:
/open-api/v1/data
- 接口路径:
/v3/api/open/ai-search/image/tiktok-shop/search
- 接口描述: 根据图片ID查询相似TikTok店铺,支持多维度过滤和排序
- 价格说明: 获取一条数据结果消耗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/tiktok-shop/search" |
是 |
|
| params |
object |
接口入参对象 |
见参数列表 |
是 |
|
请求体参数 (params 对象)
| 参数名 |
类型 |
必填 |
描述 |
| image_id |
String |
是 |
图片ID,通过图片提交接口获得。格式:img_开头+时间戳 |
| current_page |
Integer |
是 |
当前页码,从1开始,默认值是1 |
| page_size |
Integer |
是 |
每页数量,默认值是20 |
| keyword |
String |
否 |
搜索关键词,输入店铺关键词查找,如店铺名字、店铺描述 |
| region |
String |
否 |
地区,支持GB/US等地区代码,见 国家地区 |
| categorize |
String |
否 |
分类ID |
| sales_volume_min |
Long |
否 |
销量最小值 |
| sales_volume_max |
Long |
否 |
销量最大值 |
| gmv_min |
Long |
否 |
GMV(销售额)最小值 |
| gmv_max |
Long |
否 |
GMV(销售额)最大值 |
| sales_trend |
Integer |
否 |
销售趋势 (1:增长, 0:平稳, -1:下降) |
| person_count_min |
Integer |
否 |
红人数最小值 |
| person_count_max |
Integer |
否 |
红人数最大值 |
| avg_price_usd_min |
Integer |
否 |
平均销售价格(美元)最小值 |
| avg_price_usd_max |
Integer |
否 |
平均销售价格(美元)最大值 |
| delivery |
String |
否 |
店铺类型 (overseas:跨境发货, local:本地发货) |
| product_type |
String |
否 |
商品类型 (brand:品牌, retail:零售商) |
| play_count_min |
Long |
否 |
广告播放量(广告展示)最小值 |
| play_count_max |
Long |
否 |
广告播放量(广告展示)最大值 |
| cpm_min |
Integer |
否 |
最小广告花费 |
| cpm_max |
Integer |
否 |
最大广告花费 |
| video_count_min |
Long |
否 |
广告数最小值 |
| video_count_max |
Long |
否 |
广告数最大值 |
| found_time_start |
Long |
否 |
首次广告发现时间开始(Unix时间戳,秒) |
| found_time_end |
Long |
否 |
首次广告发现时间结束(Unix时间戳,秒) |
| last_found_time_start |
Long |
否 |
最后广告时间开始(Unix时间戳,秒) |
| last_found_time_end |
Long |
否 |
最后广告时间结束(Unix时间戳,秒) |
| time |
Integer |
否 |
时间范围 (0:全部, 1:昨天, 7:近7天, 30:近30天, 90:近90天)。默认:0 |
| sort |
Integer |
否 |
排序方式 (1:最后时间, 2:开始时间, 3:销量, 4:GMV, 5:广告播放量, 6:广告花费, 7:广告数, 8:红人数, 9:商品数, 10:平均销售价格, 11:图片相似度排序(默认)) |
| sort_type |
String |
否 |
排序类型 (desc:降序, asc:升序)。注意:当sort=11时此参数无效 |
请求示例
基础请求示例
使用 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/tiktok-shop/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/tiktok-shop/search",
"params": {
"image_id": "img_1737532800123456",
"current_page": 1,
"page_size": 20,
"keyword": "fashion store",
"region": "US",
"sales_volume_min": 1000,
"avg_price_usd_min": 10,
"avg_price_usd_max": 100,
"sort": 3,
"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/tiktok-shop/search",
"params": {
"image_id": "img_1737532800123456",
"current_page": 1,
"page_size": 20,
"sales_trend": 1,
"delivery": "overseas",
"product_type": "brand",
"gmv_min": 10000,
"time": 30,
"sort": 4
}
}'
响应参数
响应体结构
{
"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 |
| image |
String |
店铺主图片URL |
| title |
String |
店铺标题 |
| desc |
String |
店铺描述 |
| sales_volume |
Long |
店铺销量 |
| score |
Double |
店铺评分 |
| shop_name |
String |
店铺名称 |
| shop_id |
String |
店铺ID |
| shop_image |
String |
店铺图片URL |
| shop_sales_volume |
Long |
店铺销量 |
| video_count |
Long |
广告视频数量 |
| categorize |
List<CategoryDTO> |
店铺分类信息列表,见下方的CategoryDTO对象描述 |
| region |
List<String> |
店铺投放地区列表 |
| play_count |
Long |
播放量/广告曝光数 |
| share_count |
Long |
分享数 |
| found_time |
Long |
首次发现时间(时间戳,秒) |
| last_found_time |
Long |
最后发现时间(时间戳,秒) |
| insert_time |
Long |
数据入库时间(时间戳,秒) |
| update_time |
Long |
数据更新时间(时间戳,秒) |
| min_cpm |
Double |
最小广告花费(CPM) |
| max_cpm |
Double |
最大广告花费(CPM) |
| currency |
String |
货币类型 |
| is_collection |
Boolean |
是否已收藏 |
| root_path |
String |
店铺根路径(域名) |
| keywords |
List<String> |
店铺关键词列表 |
| card_found_time |
Long |
卡片首次发现时间(时间戳,秒) |
| card_last_found_time |
Long |
卡片最后发现时间(时间戳,秒) |
| sales_trend |
Integer |
销售趋势 (1:增长, 0:平稳, -1:下降) |
| sales_trend_data |
List<SalesTrendData> |
销售趋势数据列表, 见下方的SalesTrendData对象描述 |
| gmv |
Double |
销售额(GMV) |
| gmv_usd |
Double |
美元销售额(GMV USD) |
| is_in_marketplace |
Boolean |
是否联盟店铺 |
| is_managed |
Boolean |
是否全托管店铺 |
| person_count |
Long |
达人数量 |
| landing_page |
String |
店铺落地页URL |
| goods_count |
Long |
商品数量 |
| goods_ad_count |
String |
广告商品数量 |
| best_selling_goods |
List<BestSellingGood> |
最畅销商品列表 |
| avg_price |
Double |
平均价格(本地货币) |
| avg_price_usd |
Double |
平均美元价格 |
| product_type |
List<String> |
产品类型列表 (brand:品牌, retail:零售商) |
| delivery |
List<String> |
发货方式列表 (overseas:跨境, local:本地) |
CategoryDTO对象信息
| 字段名 |
类型 |
描述 |
| _id |
String |
分类id |
| name_zh |
String |
中文名称 |
| name_vi |
String |
越南语名称 |
| name_th |
String |
泰语名称 |
| name_pt |
String |
葡萄牙语名称 |
| name_ja |
String |
日语名称 |
| name_id |
String |
印尼语名称 |
| name_en |
String |
英文名称 |
SalesTrendData对象信息
| 字段名 |
类型 |
描述 |
| day |
Long |
统计时间(时间戳,秒) |
| sales_volume |
Long |
销量 |
BestSellingGood对象信息
| 字段名 |
类型 |
描述 |
| id |
String |
商品ID |
| image |
String |
商品图片URL |
| title |
String |
商品标题 |
| price |
Double |
商品价格 |
| sales_volume |
Long |
商品销量 |
分页信息字段 (page)
| 字段名 |
类型 |
描述 |
| total_count |
Long |
总记录数 |
| page_count |
Long |
总页数 |
| current_page |
Long |
当前页码 |
| page_size |
Long |
每页大小 |
| is_next |
Boolean |
是否有下一页 |
响应示例
{
"code": 200,
"message": "success",
"data": {
"data": [
{
"id": "shop_001",
"image": "https://cdn-shop.pipispy.com/tiktok_shop_001.jpg",
"title": "Fashion Store Official",
"desc": "Premium fashion and accessories",
"sales_volume": 125000,
"score": 4.8,
"shop_name": "Fashion Store Official",
"shop_id": "shop_12345",
"shop_image": "https://cdn-shop.pipispy.com/shop_icon.jpg",
"shop_sales_volume": 125000,
"video_count": 245,
"categorize": [
{
"_id": "cat_001",
"name_en": "Fashion",
"name_zh": "时尚"
}
],
"region": ["US", "GB"],
"play_count": 12345678,
"share_count": 45678,
"found_time": 1700000000,
"last_found_time": 1737532800,
"insert_time": 1700000000,
"update_time": 1737532800,
"min_cpm": 15.5,
"max_cpm": 45.8,
"currency": "USD",
"is_collection": false,
"root_path": "tiktok.com",
"keywords": ["fashion", "clothing", "accessories"],
"card_found_time": 1700086400,
"card_last_found_time": 1737446400,
"sales_trend": 1,
"sales_trend_data": [],
"gmv": 3750000.00,
"gmv_usd": 3750000.00,
"is_in_marketplace": true,
"is_managed": false,
"person_count": 156,
"landing_page": "https://www.tiktok.com/@fashionstore",
"goods_count": 450,
"goods_ad_count": "245",
"best_selling_goods": [
{
"id": "prod_001",
"image": "https://cdn-product.pipispy.com/prod_001.jpg",
"title": "Summer Dress",
"price": 29.99,
"sales_volume": 5000
}
],
"avg_price": 35.50,
"avg_price_usd": 35.50,
"product_type": ["brand"],
"delivery": ["overseas", "local"]
}
],
"page": {
"total_count": 500,
"page_count": 25,
"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 |
服务器内部错误 |
相关接口
完整的以图搜TikTok店铺流程涉及以下接口:
- 图片提交:
/v3/api/open/ai-search/image/submit 或 /v3/api/open/ai-search/image/submit/image-url
- 处理状态查询:
/v3/api/open/ai-search/image/status
- 结果摘要:
/v3/api/open/ai-search/image/resultSummary
- 广告搜索:
/v3/api/open/ai-search/image/search4/ad/search
- 产品搜索:
/v3/api/open/ai-search/image/product/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
使用说明
- 相似度排序: 默认情况下(sort=11),店铺列表按图片相似度排序,最相似的店铺排在最前面。注意:当sort=11时,sort_type参数无效
- 关键词搜索: 支持按店铺名字、店铺描述等维度搜索
- 地区过滤: 支持按店铺投放地区筛选
- 销售数据: 支持按销量、GMV、销售趋势等销售指标筛选
- 广告数据: 支持按广告播放量、广告数、广告花费等广告指标筛选
- 店铺类型: 支持按发货方式(跨境/本地)和商品类型(品牌/零售商)筛选
- 时间范围: 使用 time 参数可以获取指定时间范围内的店铺数据
- 达人营销: 支持按达人数量筛选,了解店铺的网红营销情况
- 价格筛选: 支持按平均销售价格筛选店铺