Pipispy APIEnglish

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

视频自然流量列表接口

接口信息

  • 接口名称: 获取视频自然流量列表
  • 请求方法: 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,实际的落地页链接地址
字段名 类型 描述
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. 页码参数从 1 开始
  2. 排序字段支持多种选项:create_time、play_count、digg_count、comment_count、share_count、digg_play_rate
  3. 搜索类型支持 4 种模式,默认为综合搜索
  4. 时间戳使用秒级时间戳
  5. 地区参数支持多个地区数组格式
  6. 点赞播放比为点赞数除以播放数的比值
  7. 视频类型 1 为自然流量视频,2 为电商视频
  8. 店铺标识 1 为普通视频,2 为电商视频