视频自然流量列表接口
接口信息
- 接口名称: 获取视频自然流量列表
- 请求方法: POST
- 接口地址:
/open-api/v1/data
- 接口路径:
/v4/api/open/video/list
- 接口描述: 根据过滤条件获取视频自然流量列表信息,支持分页查询
- 价格说明: 获取一条数据结果消耗1 credit
请求头:
- Content-Type: application/json
- Accept: application/json
请求参数
请求结构
| 参数名 |
类型 |
描述 |
示例 |
必填 |
默认值 |
| key |
string |
用户申请的外部 api 请求 key |
"your_api_key_here" |
是 |
|
| uri |
string |
接口路径 |
"/v4/api/open/video/list" |
是 |
|
| params |
object |
接口入参对象 |
见参数列表 |
是 |
|
请求体参数 (params 对象)
| 参数名 |
类型 |
必填 |
描述 |
| search_type |
Integer |
否 |
搜索类型:1-综合搜索(默认),2-视频文案搜索,3-视频主播名称搜索,4-视频链接搜索 |
| keyword |
String |
否 |
搜索关键词,根据 search_type 在不同字段中进行模糊匹配搜索 |
| type |
Integer |
否 |
视频类型:1-自然流量视频,2-TikTok 小店视频 |
| region |
Array |
否 |
国家/地区,地区列表,支持多个地区筛选,如:["US", "CN", "JP"] |
| create_time_start |
Long |
否 |
时间,视频创建时间开始时间戳(秒),用于筛选指定时间范围内创建的视频 |
| create_time_end |
Long |
否 |
时间,视频创建时间结束时间戳(秒),用于筛选指定时间范围内创建的视频 |
| follower_count_min |
Long |
否 |
创作者丝数最小值,用于筛选粉丝数大于等于此值的主播发布的视频 |
| follower_count_max |
Long |
否 |
创作者丝数最大值,用于筛选粉丝数小于等于此值的主播发布的视频 |
| play_count_min |
Long |
否 |
视频播放数最小值,用于筛选播放数大于等于此值的视频 |
| play_count_max |
Long |
否 |
视频播放数最大值,用于筛选播放数小于等于此值的视频 |
| digg_count_min |
Long |
否 |
视频点赞数最小值,用于筛选点赞数大于等于此值的视频 |
| digg_count_max |
Long |
否 |
视频点赞数最大值,用于筛选点赞数小于等于此值的视频 |
| digg_play_rate_min |
Double |
否 |
点赞率最小值,用于筛选点赞播放比大于等于此值的视频(点赞数/播放数) |
| digg_play_rate_max |
Double |
否 |
点赞率最大值,用于筛选点赞播放比小于等于此值的视频(点赞数/播放数) |
| comment_count_min |
Long |
否 |
视频评论数最小值,用于筛选评论数大于等于此值的视频 |
| comment_count_max |
Long |
否 |
视频评论数最大值,用于筛选评论数小于等于此值的视频 |
| share_count_min |
Long |
否 |
视频分享数最小值,用于筛选分享数大于等于此值的视频 |
| share_count_max |
Long |
否 |
视频分享数最大值,用于筛选分享数小于等于此值的视频 |
| current_page |
Integer |
是 |
当前页码,从 1 开始,用于分页查询 |
| page_size |
Integer |
是 |
每页大小,每页返回的数量 |
| sort_key |
String |
否 |
排序字段:create_time(创建时间)、play_count(播放数)、digg_count(点赞数)、comment_count(评论数)、share_count(分享数)、digg_play_rate(点赞播放比),默认为 create_time |
| sort_type |
String |
否 |
排序方式:asc-升序排列,desc-降序排列(默认) |
| platform |
String |
否 |
平台类型,用于筛选特定平台类型的落地页,如:shopify、woocommerce、shoplazza、magento、wix、shopline、squarespace、shopyy |
请求示例
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": "/v4/api/open/video/list",
"params": {
"search_type": 1,
"keyword": "fashion",
"type": 1,
"region": ["US", "CA"],
"create_time_start": 1640995200,
"create_time_end": 1643673600,
"follower_count_min": 10000,
"follower_count_max": 1000000,
"play_count_min": 1000,
"play_count_max": 1000000,
"digg_count_min": 100,
"digg_count_max": 50000,
"digg_play_rate_min": 0.01,
"digg_play_rate_max": 0.1,
"comment_count_min": 10,
"comment_count_max": 1000,
"share_count_min": 5,
"share_count_max": 500,
"current_page": 1,
"page_size": 20,
"sort_key": "play_count",
"sort_type": "desc",
"platform": "tiktok_shop"
}
}'
响应参数
响应体结构
{
"code": 200,
"message": "success",
"data": {
"data": [],
"page": {}
}
}
响应字段说明
| 字段名 |
类型 |
描述 |
| code |
Integer |
响应状态码,200 表示成功 |
| message |
String |
响应消息 |
| data |
Object |
响应数据 |
| data.data |
Array |
视频列表 |
| data.page |
Object |
分页信息 |
视频信息字段
| 字段名 |
类型 |
描述 |
| id |
String |
视频唯一标识 ID |
| video_url |
String |
视频播放 URL,完整的视频播放链接地址 |
| cover |
String |
视频封面图片 URL,视频的封面图片链接地址 |
| duration |
Integer |
视频时长(秒),视频的总播放时长 |
| play_count |
Long |
播放次数,视频的总播放量 |
| digg_count |
Long |
点赞次数,视频获得的总点赞数 |
| comment_count |
Long |
评论次数,视频获得的总评论数 |
| share_count |
Long |
分享次数,视频被分享的总次数 |
| create_time |
Long |
视频创建时间戳(秒),视频在 TikTok 平台上的创建时间 |
| desc |
String |
视频文案,视频的文字描述内容 |
| app_image |
String |
视频主播头像 URL,视频主播的头像图片链接地址 |
| nickname |
String |
视频主播昵称,视频主播的显示昵称 |
| follower_count |
Long |
视频主播粉丝数,视频主播的总粉丝数量 |
| fetch_region |
String |
数据获取地区,视频数据来源的地区标识 |
| author_url |
String |
视频主播主页 URL,视频主播的 TikTok 主页链接 |
| landing_page |
Array |
落地页信息列表,视频关联的电商落地页信息 |
| products |
Array |
商品信息列表,视频关联的商品详细信息 |
| review_count |
Long |
评论总数,视频的评论总数(包括回复) |
| tiktok_url |
String |
TikTok 视频链接,视频在 TikTok 平台上的完整链接地址 |
| is_collection |
Boolean |
是否已收藏,当前用户是否已收藏该视频 |
| type |
Integer |
视频类型,1-普通视频,其他值-特殊类型视频 |
| carousel |
Array |
轮播图列表,视频的轮播图片信息 |
| shop_flag |
Integer |
店铺标识,1-普通视频,2-电商视频(tiktok_shop) |
商品信息字段 (products 数组)
| 字段名 |
类型 |
描述 |
| image |
String |
商品图片 URL,商品的展示图片链接 |
| name |
String |
商品名称,商品的标题名称 |
| currency |
String |
货币类型,商品价格的货币单位,如:USD、CNY |
| price |
Double |
商品价格,商品的销售价格 |
| url |
String |
商品链接,商品的购买链接地址 |
落地页信息字段 (landing_page 数组)
| 字段名 |
类型 |
描述 |
| type |
String |
落地页类型,如:tiktok_shop 等平台类型 |
| url |
String |
落地页 URL,实际的落地页链接地址 |
轮播图信息字段 (carousel 数组)
| 字段名 |
类型 |
描述 |
| type |
Integer |
轮播图类型,2-图片类型 |
| image |
String |
轮播图片 URL,轮播图的图片链接地址 |
分页信息字段
| 字段名 |
类型 |
描述 |
| total_count |
Long |
总记录数 |
| page_count |
Long |
总页数 |
| current_page |
Long |
当前页码 |
| page_size |
Long |
每页记录数 |
| is_next |
Boolean |
是否有下一页 |
响应示例
{
"code": 200,
"message": "success",
"data": {
"data": [
{
"id": "507f1f77bcf86cd799439011",
"video_url": "https://example.com/video.mp4",
"cover": "https://example.com/cover.jpg",
"duration": 30,
"play_count": 500000,
"digg_count": 25000,
"comment_count": 1200,
"share_count": 800,
"create_time": 1640995200,
"desc": "时尚穿搭分享,超好看的搭配推荐",
"app_image": "https://example.com/avatar.jpg",
"nickname": "时尚达人",
"follower_count": 500000,
"fetch_region": "US",
"author_url": "https://www.tiktok.com/@fashion_expert",
"landing_page": [
{
"type": "tiktok_shop",
"url": "https://shop.tiktok.com/product/123"
}
],
"products": [
{
"image": "https://example.com/product.jpg",
"name": "时尚运动鞋",
"currency": "USD",
"price": 99.99,
"url": "https://shop.tiktok.com/product/123"
}
],
"review_count": 1500,
"tiktok_url": "https://www.tiktok.com/@fashion_expert/video/507f1f77bcf86cd799439011",
"is_collection": false,
"type": 1,
"carousel": [
{
"type": 2,
"image": "https://example.com/carousel1.jpg"
}
],
"shop_flag": 2
}
],
"page": {
"total_count": 1250,
"page_count": 63,
"current_page": 1,
"page_size": 20,
"is_next": true
}
}
}
错误码说明
| 错误码 |
描述 |
| 200 |
成功 |
| 400 |
请求参数错误 |
| 500 |
服务器内部错误 |
注意事项
- 页码参数从 1 开始
- 排序字段支持多种选项:create_time、play_count、digg_count、comment_count、share_count、digg_play_rate
- 搜索类型支持 4 种模式,默认为综合搜索
- 时间戳使用秒级时间戳
- 地区参数支持多个地区数组格式
- 点赞播放比为点赞数除以播放数的比值
- 视频类型 1 为自然流量视频,2 为电商视频
- 店铺标识 1 为普通视频,2 为电商视频