以图搜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-product/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-product/search" |
是 |
|
| params |
object |
接口入参对象 |
见参数列表 |
是 |
|
请求体参数 (params 对象)
| 参数名 |
类型 |
必填 |
描述 |
| image_id |
String |
是 |
图片ID,通过图片提交接口获得。格式:img_开头+时间戳 |
| current_page |
Integer |
是 |
当前页码,从1开始,默认值是1 |
| page_size |
Integer |
是 |
每页数量,默认值是20 |
| search_type |
Integer |
否 |
搜索类型 (1:根据产品名称(描述)搜索, 2:根据店铺名称搜索, 3:根据红人名称搜索)。默认:1 |
| keyword |
String |
否 |
搜索关键词,配合search_type使用 |
| 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 |
否 |
红人数最大值 |
| price_usd_min |
Integer |
否 |
价格(美元)最小值 |
| price_usd_max |
Integer |
否 |
价格(美元)最大值 |
| delivery |
String |
否 |
发货方式 (overseas:跨境发货, local:本地发货) |
| 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:按相似度排序(默认)) |
| sort_type |
String |
否 |
排序类型 (desc:降序, asc:升序) |
| is_in_marketplace |
Boolean |
否 |
是否联盟商品,非必填 true/false |
| commission_rate |
Double |
否 |
佣金比例,取值0-1之间 |
请求示例
基础请求示例
使用 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-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/tiktok-product/search",
"params": {
"image_id": "img_1737532800123456",
"current_page": 1,
"page_size": 20,
"search_type": 1,
"keyword": "fashion",
"region": "US",
"sales_volume_min": 1000,
"price_usd_min": 10,
"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-product/search",
"params": {
"image_id": "img_1737532800123456",
"current_page": 1,
"page_size": 20,
"sales_trend": 1,
"delivery": "overseas",
"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 |
商品描述 |
| price |
Double |
商品价格(本地货币) |
| price_usd |
Double |
商品美元价格 |
| sales_volume |
Long |
商品销量 |
| score |
Double |
商品评分 |
| shop_name |
String |
店铺名称 |
| shop_id |
String |
店铺ID |
| shop_image |
String |
店铺图片URL |
| shop_sales_volume |
Long |
店铺销量 |
| video_count |
Long |
广告视频数量 |
| categorize |
CategoryDTO |
商品分类信息,见下方的CategoryDTO对象描述 |
| region |
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 |
卡片最后发现时间(时间戳,秒) |
| commission_rate |
Double |
佣金比例,取值0-1之间 |
| sales_trend |
Integer |
销售趋势 (1:增长, 0:平稳, -1:下降) |
| sales_trend_data |
List<SalesTrendData> |
销售趋势数据列表, 见下方的SalesTrendData对象描述 |
| gmv |
Double |
销售额(GMV) |
| gmv_usd |
Double |
美元销售额(GMV USD) |
| delivery |
String |
发货方式 (overseas:跨境, local:本地) |
| is_in_marketplace |
Boolean |
是否联盟商品,非必填 true/false |
| is_managed |
Boolean |
是否全托管商品 |
| person_count |
Long |
达人数量 |
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 |
销量 |
分页信息字段 (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",
"image": "https://cdn-product.pipispy.com/tiktok_product_001.jpg",
"title": "Wireless Bluetooth Earbuds",
"desc": "High quality wireless earbuds with noise cancellation",
"price": 29.99,
"price_usd": 29.99,
"sales_volume": 15234,
"score": 4.8,
"shop_name": "TechStore Official",
"shop_id": "shop_12345",
"shop_image": "https://cdn-shop.pipispy.com/shop_icon.jpg",
"shop_sales_volume": 125000,
"video_count": 45,
"categorize": {
"id": "cat_001",
"name": "Electronics"
},
"region": "US",
"play_count": 2345678,
"share_count": 12345,
"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": ["wireless", "bluetooth", "earbuds"],
"card_found_time": 1700086400,
"card_last_found_time": 1737446400,
"commission_rate": 0.15,
"sales_trend": 1,
"sales_trend_data": [],
"gmv": 456789.50,
"gmv_usd": 456789.50,
"delivery": "overseas",
"is_in_marketplace": true,
"is_managed": false,
"person_count": 23
},
{
"id": "product_002",
"image": "https://cdn-product.pipispy.com/tiktok_product_002.jpg",
"title": "Smart Watch Fitness Tracker",
"desc": "Advanced fitness tracker with heart rate monitor",
"price": 49.99,
"price_usd": 49.99,
"sales_volume": 8765,
"score": 4.6,
"shop_name": "FitGear Store",
"shop_id": "shop_67890",
"shop_image": "https://cdn-shop.pipispy.com/shop_icon2.jpg",
"shop_sales_volume": 89000,
"video_count": 32,
"categorize": {
"id": "cat_002",
"name": "Wearables"
},
"region": "GB",
"play_count": 1234567,
"share_count": 8901,
"found_time": 1699913600,
"last_found_time": 1737446400,
"insert_time": 1699913600,
"update_time": 1737446400,
"min_cpm": 18.2,
"max_cpm": 52.3,
"currency": "USD",
"is_collection": true,
"root_path": "tiktok.com",
"keywords": ["smartwatch", "fitness", "tracker"],
"card_found_time": 1700000000,
"card_last_found_time": 1737360000,
"commission_rate": 0.12,
"sales_trend": 0,
"sales_trend_data": [],
"gmv": 437823.35,
"gmv_usd": 437823.35,
"delivery": "local",
"is_in_marketplace": true,
"is_managed": true,
"person_count": 18
}
],
"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 |
服务器内部错误 |
相关接口
完整的以图搜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=9),商品列表按图片相似度降序排列,最相似的商品排在最前面
- 关键词搜索: 支持按产品名称、店铺名称、红人名称等不同维度搜索
- 地区过滤: 支持按商品投放地区筛选
- 销售数据: 支持按销量、GMV、销售趋势等销售指标筛选
- 广告数据: 支持按广告播放量、广告数、广告花费等广告指标筛选
- 发货方式: 支持按跨境发货或本地发货筛选
- 时间范围: 使用 time 参数可以获取指定时间范围内的商品数据
- 达人营销: 支持按达人数量筛选,了解商品的网红营销情况