# 以图搜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等地区代码,见 [国家地区](https://www.pipispy.com/zh/doc/others-region) | | 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 ```bash 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 } }' ``` ### 高级过滤示例 #### 使用关键词和地区过滤 ```bash 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" } }' ``` #### 按销售趋势和发货方式过滤 ```bash 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 } }' ``` --- ## 响应参数 ### 响应体结构 ```json { "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\ | 商品关键词列表 | | 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对象描述 | | 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 | 是否有下一页 | --- ## 响应示例 ```json { "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产品流程涉及以下接口: 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. **关键词搜索**: 支持按产品名称、店铺名称、红人名称等不同维度搜索 3. **地区过滤**: 支持按商品投放地区筛选 4. **销售数据**: 支持按销量、GMV、销售趋势等销售指标筛选 5. **广告数据**: 支持按广告播放量、广告数、广告花费等广告指标筛选 6. **发货方式**: 支持按跨境发货或本地发货筛选 7. **时间范围**: 使用 time 参数可以获取指定时间范围内的商品数据 8. **达人营销**: 支持按达人数量筛选,了解商品的网红营销情况