SNSTrackerSNSTracker

API 接口文档

概述

SNSTracker API 允许您通过编程方式管理监控动态和频道。您可以创建动态（视频、帖子等）和频道（账号、个人资料），刷新它们以获取最新数据，并通过 webhook 接收实时通知。

认证

所有 API 请求都需要使用 API 密钥进行认证。请在 X-API-Key 请求头中包含您的 API 密钥。

如何获取 API 密钥：

  1. 登录 SNSTracker
  2. 进入 设置 → API 密钥
  3. 创建新的 API 密钥或使用现有的密钥
  4. 复制 API 密钥（创建时只会显示一次）

API 接口

1. 创建动态

通过提交动态 URL（视频、帖子等）来创建监控动态。

POST /api/v1/feeds

请求

请求头：

  • X-API-Key: 您的 API 密钥（必需）
  • Content-Type: application/json

请求体：

{
  "urls": [
    "https://www.tiktok.com/@user/video/1234567890",
    "https://www.instagram.com/p/ABC123/"
  ],
  "collectionId": "coll_abc123xyz"
}

参数说明：

  • urls（必需）：要监控的动态 URL 数组。每次请求最多 200 个 URL。
  • collectionId（可选）：动态将被添加到的集合 ID。如果未提供，将使用您团队的默认集合。

响应

成功响应 (200)：

{
  "code": 0,
  "message": "ok",
  "data": {
    "success": 2,
    "failed": 0,
    "total": 2,
    "results": [
      {
        "index": 0,
        "url": "https://www.tiktok.com/@user/video/1234567890",
        "platform": "tiktok",
        "feedId": "feed_abc123xyz",
        "success": true
      },
      {
        "index": 1,
        "url": "https://www.instagram.com/p/ABC123/",
        "platform": "instagram",
        "feedId": "feed_def456uvw",
        "success": true
      }
    ],
    "errors": [],
    "message": "Feeds created successfully. Data will be updated shortly."
  }
}

响应字段说明：

  • success: 成功创建的动态数量
  • failed: 创建失败的动态数量
  • total: 提供的 URL 总数
  • results: 每个 URL 的结果数组
    • index: 在请求数组中的索引（从 0 开始）
    • url: 验证并标准化后的 URL
    • platform: 检测到的平台（tiktok、instagram、youtube 等）
    • feedId: 创建的动态的唯一标识符
    • success: 动态是否创建成功
    • skipped: （可选）是否因为已存在而跳过
    • resumed: （可选）是否恢复了已停止的动态
    • error: （可选）如果创建失败，错误消息
  • errors: 失败 URL 的错误数组

请求示例

curl -X POST https://snstracker.com/api/v1/feeds \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://www.tiktok.com/@user/video/1234567890"
    ]
  }'

2. 刷新动态

立即刷新现有动态以获取最新数据。只有状态为"待处理"或"追踪中"的动态可以被刷新。

POST /api/v1/feeds/refresh

请求

请求头：

  • X-API-Key: 您的 API 密钥（必需）
  • Content-Type: application/json

请求体：

{
  "feedIds": ["feed_abc123xyz", "feed_def456uvw"]
}

参数说明：

  • feedIds（必需）：要刷新的动态 ID 数组

响应

成功响应 (200)：

{
  "code": 0,
  "message": "ok",
  "data": {
    "success": true,
    "feedIds": ["feed_abc123xyz", "feed_def456uvw"],
    "total": 2,
    "message": "Successfully refreshed 2 feed(s)"
  }
}

响应字段说明：

  • success: 刷新操作是否成功
  • feedIds: 被刷新的动态 ID 数组
  • total: 刷新的动态数量
  • message: 成功消息

请求示例

curl -X POST https://snstracker.com/api/v1/feeds/refresh \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "feedIds": ["feed_abc123xyz"]
  }'

3. 创建频道

通过提交频道 URL（账号个人资料等）来创建监控频道。

渠道计费说明：小红书渠道任务已从默认频道任务价格中单独拆分计价，当前仍为每次成功请求 10 积分。

POST /api/v1/channels

请求

请求头：

  • X-API-Key: 您的 API 密钥（必需）
  • Content-Type: application/json

请求体：

{
  "urls": [
    "https://www.tiktok.com/@username",
    "https://www.instagram.com/username/"
  ],
  "collectionId": "coll_abc123xyz"
}

参数说明：

  • urls（必需）：要监控的频道 URL 数组。每次请求最多 200 个 URL。
  • collectionId（可选）：频道将被添加到的集合 ID。如果未提供，将使用您团队的默认集合。

响应

成功响应 (200)：

{
  "code": 0,
  "message": "ok",
  "data": {
    "success": 2,
    "failed": 0,
    "total": 2,
    "results": [
      {
        "index": 0,
        "url": "https://www.tiktok.com/@username",
        "platform": "tiktok",
        "channelId": "channel_abc123xyz",
        "success": true
      },
      {
        "index": 1,
        "url": "https://www.instagram.com/username/",
        "platform": "instagram",
        "channelId": "channel_def456uvw",
        "success": true
      }
    ],
    "errors": [],
    "message": "Channels created successfully. Data will be updated shortly."
  }
}

响应字段说明：

  • success: 成功创建的频道数量
  • failed: 创建失败的频道数量
  • total: 提供的 URL 总数
  • results: 每个 URL 的结果数组
    • index: 在请求数组中的索引（从 0 开始）
    • url: 验证并标准化后的 URL
    • platform: 检测到的平台（tiktok、instagram、youtube 等）
    • channelId: 创建的频道的唯一标识符
    • success: 频道是否创建成功
    • skipped: （可选）是否因为已存在而跳过
    • resumed: （可选）是否恢复了已停止的频道
    • error: （可选）如果创建失败，错误消息
  • errors: 失败 URL 的错误数组

请求示例

curl -X POST https://snstracker.com/api/v1/channels \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://www.tiktok.com/@username"
    ]
  }'

4. 刷新频道

立即刷新现有频道以获取最新数据。只有状态为"待处理"或"追踪中"的频道可以被刷新。

渠道计费说明：小红书渠道任务已从默认频道任务价格中单独拆分计价，当前仍为每次成功请求 10 积分。

POST /api/v1/channels/refresh

请求

请求头：

  • X-API-Key: 您的 API 密钥（必需）
  • Content-Type: application/json

请求体：

{
  "channelIds": ["channel_abc123xyz", "channel_def456uvw"]
}

参数说明：

  • channelIds（必需）：要刷新的频道 ID 数组

响应

成功响应 (200)：

{
  "code": 0,
  "message": "ok",
  "data": {
    "success": true,
    "channelIds": ["channel_abc123xyz", "channel_def456uvw"],
    "total": 2,
    "message": "Successfully refreshed 2 channel(s)"
  }
}

响应字段说明：

  • success: 刷新操作是否成功
  • channelIds: 被刷新的频道 ID 数组
  • total: 刷新的频道数量
  • message: 成功消息

请求示例

curl -X POST https://snstracker.com/api/v1/channels/refresh \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "channelIds": ["channel_abc123xyz"]
  }'

5. 同步动态

直接从 scrapy 服务同步动态数据。此接口会立即获取最新的动态数据，并在同步成功后扣除积分。同一团队的所有成员、API Key 和所有同步接口共享一个并发上限：入门版或无有效订阅为 1，标准版为 5，高级版为 10。

⚠️ 重要提示： 此同步接口是独立的，不会与 Web 平台集成。同步操作将：

  • 不会在 Web 仪表板中创建或更新动态记录
  • 不会出现在您的动态列表或集合中
  • 不会触发 webhook 或通知
  • 仅在 API 响应中直接返回获取的数据

此接口设计用于通过 API 进行一次性数据检索。要创建在 Web 平台中显示的持久监控动态，请使用创建动态接口。

POST /api/v1/feeds/sync

请求

请求头：

  • X-API-Key: 您的 API 密钥（必需）
  • Content-Type: application/json

请求体：

{
  "url": "https://www.tiktok.com/@user/video/1234567890"
}

参数说明：

  • url（必需）：要同步的动态 URL。必须是有效的非空字符串。

响应

成功响应 (200)：

{
  "code": 0,
  "message": "ok",
  "data": {
    "success": true,
    "url": "https://www.tiktok.com/@user/video/1234567890",
    "feedInfo": {
      "feed_id": "1234567890",
      "platform": 1,
      "platform_name": "tiktok",
      "url": "https://www.tiktok.com/@user/video/1234567890",
      "views": 1000000,
      "likes": 200000,
      "comments": 1000,
      "shares": 2000,
      "bookmarks": 200,
      "engagement": 512000,
      "description": "视频描述",
      "hash_tags": ["标签1", "标签2"],
      "publish_at": 1234567890
    }
  }
}

响应字段说明：

  • success: 同步操作是否成功
  • url: 已同步的动态 URL
  • feedInfo: 完整的动态信息，包括指标、描述、标签等

错误响应：

  • 429 Too Many Requests: 团队共享并发量已满，请求不会排队。
  • 400 Bad Request: 积分不足或 URL 无效

请求示例

curl -X POST https://snstracker.com/api/v1/feeds/sync \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.tiktok.com/@user/video/1234567890"
  }'

6. 同步频道

直接从 scrapy 服务同步频道数据。此接口会立即获取最新的频道数据，并在同步成功后扣除积分。同一团队的所有成员、API Key 和所有同步接口共享一个并发上限：入门版或无有效订阅为 1，标准版为 5，高级版为 10。

渠道计费说明：小红书渠道任务已从默认频道任务价格中单独拆分计价，当前仍为每次成功请求 10 积分。

⚠️ 重要提示： 此同步接口是独立的，不会与 Web 平台集成。同步操作将：

  • 不会在 Web 仪表板中创建或更新频道记录
  • 不会出现在您的频道列表或集合中
  • 不会触发 webhook 或通知
  • 仅在 API 响应中直接返回获取的数据

此接口设计用于通过 API 进行一次性数据检索。要创建在 Web 平台中显示的持久监控频道，请使用创建频道接口。

POST /api/v1/channels/sync

请求

请求头：

  • X-API-Key: 您的 API 密钥（必需）
  • Content-Type: application/json

请求体：

{
  "url": "https://www.tiktok.com/@username"
}

参数说明：

  • url（必需）：要同步的频道 URL。必须是有效的非空字符串。

响应

成功响应 (200)：

{
  "code": 0,
  "message": "ok",
  "data": {
    "success": true,
    "url": "https://www.tiktok.com/@username",
    "channelInfo": {
      "id": "1234567890",
      "platform": 1,
      "platform_name": "tiktok",
      "username": "username",
      "nickname": "用户名",
      "description": "频道描述",
      "followers": 1000000,
      "followings": 2000,
      "likes": 200000000,
      "total_count": 1000,
      "track_count": 1000,
      "status": 1
    }
  }
}

响应字段说明：

  • success: 同步操作是否成功
  • url: 已同步的频道 URL
  • channelInfo: 完整的频道信息，包括指标、描述等

错误响应：

  • 429 Too Many Requests: 团队共享并发量已满，请求不会排队。
  • 400 Bad Request: 积分不足或 URL 无效

请求示例

curl -X POST https://snstracker.com/api/v1/channels/sync \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.tiktok.com/@username"
  }'

7. 同步频道内容（游标分页）

每次仅返回频道主页的一页内容。Instagram 和 Reels 每次最多返回 12 条，不自动翻页。instagram 返回 Posts（图片、视频和轮播帖子）；reels 只返回 Reels 视频。

POST /api/v1/channels/feeds/sync
X-API-Key: your-api-key
Content-Type: application/json

请求与翻页

{
  "platform": "instagram",
  "channel_name": "instagram"
}
  • count 可选，正整数，表示本页期望返回的条数，无默认值。数量限制依平台而定：Instagram 和 Reels 每次最多返回 12 条，实际返回可能更少。不填时使用平台默认页大小。一条轮播算一条帖子。
  • 不传 cursor 获取第一页；下一次原样传回上次响应的 next_cursor，并保持 platform、channel_name 不变。没有下一页时返回 has_more=false、next_cursor=null；空页仍可能有下一页。
{
  "platform": "instagram",
  "channel_name": "instagram",
  "cursor": "previous-next-cursor"
}

每个成功返回的页面扣 10 积分，包括没有内容的空页；只有请求出错才不扣费；请求前需至少有 10 积分。每页请求与其他同步接口共用团队并发额度，不创建仪表板记录。

响应结构示例（reels、lunacut.edit、count=1，游标为占位符）

{
  "code": 0,
  "message": "ok",
  "data": {
    "success": true,
    "platform": "reels",
    "channel_name": "lunacut.edit",
    "channel_url": "https://www.instagram.com/lunacut.edit/",
    "requested_count": 1,
    "returned_count": 1,
    "has_more": true,
    "next_cursor": "cursor-from-response",
    "items": [
      {
        "feed_id": "4009169989985582972",
        "platform": 5,
        "platform_name": "reels",
        "type": "video",
        "url": "https://www.instagram.com/reel/Dejbt1JPz98/",
        "author_username": "lunacut.edit",
        "publish_at": 1792150387,
        "duration": 70.077,
        "view_count": 310475
      }
    ]
  }
}

platform 和 channel_name 为必填参数。channel_name 为用户名（不是昵称），支持前导 @，保留点号。requested_count 在省略 count 时为 null；returned_count 等于 items.length。未知统计值和时间为 null；Posts 可能缺失发布时间及轮播明细。items 使用现有内容字段，包括 video_url、image_urls、cover_url；示例仅展示部分字段。publish_at 为 Unix 秒，duration 为秒。保留上游顺序，不提供最热排序；建议按 feed_id 跨页去重。

items 中的播放量（view_count）、点赞数（like_count）、收藏数（bookmark_count）、评论数（comment_count）等指标，取决于平台及其主页列表接口提供的数据，并非每个平台都能获取全部指标。未获取到的指标返回 null，不代表数值为 0。

如需补查主页列表未提供的指标，需使用该条目的 url，单独调用 POST /api/v1/feeds/sync，请求体中的 url 填入该内容链接。详情查询按该接口的规则独立计费；结果仍以平台实际可提供的数据为准，不保证补齐全部指标。

HTTP 状态：400 参数或游标无效、初始积分不足；401 API Key 无效；402 结算时积分不足；403 团队禁用或频道不可访问；429 团队并发已满（Retry-After: 1）；502 上游失败或页面异常；503 服务不可用；504 超时。

8. 获取主页额外信息

POST /api/v1/channels/about/sync

目前仅支持 Instagram 和 Reels，输入与 /api/v1/channels/sync 相同，只需必填的 url。Instagram 使用 https://www.instagram.com/lunacut.edit/，Reels 使用 https://www.instagram.com/lunacut.edit/reels/。无需传 platform、count 或 cursor；不支持帖子链接和其他平台。

curl -X POST https://snstracker.com/api/v1/channels/about/sync \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.instagram.com/lunacut.edit/"}'

每次成功请求扣 80 积分，额外字段为空（null）也扣费；请求出错不扣费，请求前需至少有 80 积分。本接口与其他同步接口共享团队并发量：入门版或无有效订阅为 1、标准版为 5、高级版为 10。仅返回数据，不创建仪表板记录，也不发送 webhook。

以下为响应示例，字段是否可用取决于账号公开信息。

{
  "code": 0,
  "message": "ok",
  "data": {
    "success": true,
    "url": "https://www.instagram.com/lunacut.edit/",
    "channelAbout": {
      "platform": 6,
      "platform_name": "instagram",
      "username": "lunacut.edit",
      "channel_url": "https://www.instagram.com/lunacut.edit/",
      "country": "Brazil",
      "country_visible": true,
      "date_joined": "2020-05",
      "date_joined_text": "May 2020"
    }
  }
}

country：账号公开显示的国家/地区，仅在 country_visible=true 时返回，不是实时 IP 位置。country_visible：是否公开地区，未知时为 null。date_joined：加入 Instagram 的年月，格式为 YYYY-MM，缺失或无法识别时为 null，不补造具体日期。date_joined_text：原始加入时间文本，缺失时为 null。不包含 Bio、粉丝数或曾用名。

错误：400 URL 无效、平台不支持或初始积分不足；401 API Key 无效；403 团队已禁用；402 结算时积分不足；429 团队共享并发量已满（Retry-After: 1）；502 上游失败或响应异常；503 服务不可用；504 超时。

Webhook 集成

SNSTracker 支持 webhook 来接收实时通知，当监控的内容达到您配置的阈值时。您可以配置 webhook 来接收以下通知：

  • 动态更新：当观看数、互动数（点赞 + 评论 + 分享）按您的阈值增加时
  • 频道更新：当粉丝数、关注数或点赞数按您的阈值增加时

设置 Webhook

  1. 在集合设置中配置 webhook 目标
  2. 在集合配置中启用通知
  3. 设置阈值以监控您关心的指标

有关详细的 webhook 配置说明，请参考 Webhook 配置教程。

错误响应

所有接口可能返回以下错误响应：

401 未授权 - 缺少 API 密钥

{
  "code": -1,
  "message": "X-API-Key header is required"
}

401 未授权 - 无效的 API 密钥

{
  "code": -1,
  "message": "Invalid API key"
}

400 错误请求 - 无效输入

{
  "code": -1,
  "message": "Invalid request: urls must be an array"
}

400 错误请求 - URL 数量过多（创建动态）

{
  "code": -1,
  "message": "Maximum 200 URLs allowed per request"
}

400 错误请求 - URL 数量过多（创建频道）

{
  "code": -1,
  "message": "Maximum 200 URLs allowed per request"
}

400 错误请求 - 积分不足

{
  "code": -1,
  "message": "Insufficient credits. Required: 10, Available: 5"
}

429 Too Many Requests - 团队同步并发量

{
  "code": -1,
  "message": "Maximum concurrent sync requests (1) reached for this team. Currently active: 1. Wait for a request to complete, or contact official support to increase the limit."
}

403 禁止访问 - 无效的集合

{
  "code": -1,
  "message": "Collection not found or does not belong to your team"
}

404 未找到

{
  "code": -1,
  "message": "No feeds found"
}

或

{
  "code": -1,
  "message": "No channels found"
}

使用示例

Python 示例 - 创建动态

import requests

url = "https://snstracker.com/api/v1/feeds"
headers = {
    "X-API-Key": "your-api-key-here",
    "Content-Type": "application/json"
}
data = {
    "urls": [
        "https://www.tiktok.com/@user/video/1234567890",
        "https://www.instagram.com/p/ABC123/"
    ]
}

response = requests.post(url, json=data, headers=headers)
result = response.json()

if result["code"] == 0:
    print(f"成功创建 {result['data']['success']} 个动态")
    for feed in result["data"]["results"]:
        print(f"  - {feed['url']}: {feed['feedId']}")
else:
    print(f"错误: {result['message']}")

JavaScript 示例 - 刷新动态

const response = await fetch('https://snstracker.com/api/v1/feeds/refresh', {
  method: 'POST',
  headers: {
    'X-API-Key': 'your-api-key-here',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    feedIds: ['feed_abc123xyz', 'feed_def456uvw'],
  }),
});

const result = await response.json();

if (result.code === 0) {
  console.log(`成功刷新 ${result.data.total} 个动态`);
  result.data.feedIds.forEach((feedId) => {
    console.log(`  - ${feedId}`);
  });
} else {
  console.error(`错误: ${result.message}`);
}

重要提示

  1. URL 验证：所有 URL 在创建前都会自动验证。无效的 URL 将被拒绝。

  2. 重复项目：如果集合中已存在相同 URL 的项目：

    • 如果它是活跃的，将被跳过（标记为 skipped: true）
    • 如果它已停止，将被恢复（标记为 resumed: true）

  3. 数据采集：成功创建后，项目会被加入数据采集队列。数据将在创建后不久可用。

  4. 刷新状态：只有状态为"待处理"或"追踪中"的项目可以被刷新。其他状态的项目将被过滤。

  5. 积分：在发起请求之前，请确保您有足够的积分。同步操作在成功获取数据后会立即扣除积分。 小红书渠道任务单独计价，当前每次成功请求 10 积分。 /api/v1/channels/feeds/sync: 每个成功返回的页面扣 10 积分，包括没有内容的空页；只有请求出错才不扣费；请求前需至少有 10 积分。每页请求与其他同步接口共用团队并发额度，不创建仪表板记录。 /api/v1/channels/about/sync: 每次成功请求扣 80 积分，额外字段为空（null）也扣费；请求出错不扣费，请求前需至少有 80 积分。本接口与其他同步接口共享团队并发量：入门版或无有效订阅为 1、标准版为 5、高级版为 10。仅返回数据，不创建仪表板记录，也不发送 webhook。

  6. 团队同步并发量 (/api/v1/feeds/sync + /api/v1/channels/sync + /api/v1/channels/feeds/sync + /api/v1/channels/about/sync): 同一团队的所有成员、API Key 和所有同步接口共享一个并发上限：入门版或无有效订阅为 1，标准版为 5，高级版为 10。 额度随当前有效套餐自动变化；官方为团队单独配置时，以该配置为准。 如需提升团队并发量，请联系官方。

  7. 同步 vs 创建：同步接口（/api/v1/feeds/sync、/api/v1/channels/sync 和 /api/v1/channels/feeds/sync + /api/v1/channels/about/sync）是独立的，不会与 Web 平台集成。它们仅在 API 响应中返回数据，不会在仪表板中创建记录。要创建在 Web 平台中显示的持久监控项目，请使用创建接口（/api/v1/feeds 和 /api/v1/channels）。

  8. 重试：收到 429 后，等待正在执行的请求完成，并遵循 Retry-After 响应头进行退避重试；收到 503 表示服务暂时不可用，请稍后重试。

  9. 支持的平台：TikTok、Instagram、YouTube 和其他主要社交媒体平台。

故障排除

问题："X-API-Key header is required"
解决方案：确保在请求中包含 X-API-Key 请求头。

问题："Invalid API key"
解决方案：验证您的 API 密钥是否正确。您可以从设置 → API 密钥创建新的密钥。

问题："Maximum URLs allowed per request"
解决方案：将您的 URL 分成多个请求。动态每次最多允许 200 个 URL，频道每次最多允许 5 个 URL。

问题："No collection found"
解决方案：先在仪表板中创建一个集合，或指定一个现有的集合 ID。

问题："Insufficient credits"
解决方案：购买更多积分或检查您的订阅计划。

问题："No refreshable items found"
解决方案：只有状态为"待处理"或"追踪中"的项目可以被刷新。请检查您的项目状态。

问题：某些 URL 验证失败
解决方案：检查响应中的 errors 数组以获取具体的错误消息。确保 URL 来自支持的平台且可公开访问。

Webhook 配置教程

Next Page

On this page

概述
认证
API 接口
1. 创建动态
请求
响应
请求示例
2. 刷新动态
请求
响应
请求示例
3. 创建频道
请求
响应
请求示例
4. 刷新频道
请求
响应
请求示例
5. 同步动态
请求
响应
请求示例
6. 同步频道
请求
响应
请求示例
7. 同步频道内容（游标分页）
请求与翻页
响应结构示例（reels、lunacut.edit、count=1，游标为占位符）
8. 获取主页额外信息
Webhook 集成
设置 Webhook
错误响应
401 未授权 - 缺少 API 密钥
401 未授权 - 无效的 API 密钥
400 错误请求 - 无效输入
400 错误请求 - URL 数量过多（创建动态）
400 错误请求 - URL 数量过多（创建频道）
400 错误请求 - 积分不足
429 Too Many Requests - 团队同步并发量
403 禁止访问 - 无效的集合
404 未找到
使用示例
Python 示例 - 创建动态
JavaScript 示例 - 刷新动态
重要提示
故障排除