API 介面文件
概述
SNSTracker API 允許您透過程式方式管理監控動態與頻道。您可以建立動態(影片、貼文等)與頻道(帳號、個人檔案),刷新以取得最新資料,並透過 webhook 接收即時通知。
認證
所有 API 請求都需要使用 API 金鑰進行認證。請在 X-API-Key 請求標頭中包含您的 API 金鑰。
如何取得 API 金鑰:
- 登入 SNSTracker
- 進入 設定 → API 金鑰
- 建立新的 API 金鑰或使用既有的金鑰
- 複製 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: 驗證並標準化後的 URLplatform: 偵測到的平台(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: 驗證並標準化後的 URLplatform: 偵測到的平台(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: 已同步的動態 URLfeedInfo: 完整的動態資訊,包含指標、描述、標籤等
錯誤回應:
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: 已同步的頻道 URLchannelInfo: 完整的頻道資訊,包含指標、描述等
錯誤回應:
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 是使用者名稱(不是暱稱),支援前導 @ 並保留點號。省略 count 時 requested_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
- 在集合設定中設定 webhook 目標
- 在集合設定中啟用通知
- 設定門檻以監控您關心的指標
有關詳細的 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}`);
}重要提示
-
URL 驗證:所有 URL 在建立前都會自動驗證。無效的 URL 將被拒絕。
-
重複項目:如果集合中已存在相同 URL 的項目:
- 如果它是活躍的,將被略過(標記為
skipped: true) - 如果它已停止,將被恢復(標記為
resumed: true)
- 如果它是活躍的,將被略過(標記為
-
資料採集:成功建立後,項目會被加入資料採集佇列。資料將在建立後不久可用。
-
刷新狀態:只有狀態為「待處理」或「追蹤中」的項目可以被刷新。其他狀態的項目將被過濾。
-
點數:在發起請求之前,請確保您有足夠的點數。同步操作在成功取得資料後會立即扣除點數。 小紅書渠道任務單獨計價,目前每次成功請求 10 點數。
/api/v1/channels/feeds/sync: 每個成功回傳的頁面扣 10 積分,包括沒有內容的空頁;只有請求出錯才不扣費;請求前至少需有 10 積分。每頁與其他同步介面共用團隊併發額度,不建立儀表板紀錄。/api/v1/channels/about/sync: 每次成功請求扣 80 點數,額外欄位為空(null)也扣費;請求出錯不扣費,請求前至少需有 80 點數。本介面與其他同步介面共用團隊並行額度:入門版或無有效訂閱為 1、標準版為 5、高級版為 10。僅回傳資料,不建立儀表板記錄,也不發送 webhook。 -
團隊同步併發量 (
/api/v1/feeds/sync+/api/v1/channels/sync+/api/v1/channels/feeds/sync+/api/v1/channels/about/sync): 同一團隊的所有成員、API Key 和所有同步介面共用一個併發上限:入門或無有效訂閱為 1、標準為 5、高階為 10。 額度隨目前有效方案自動變更;官方為團隊單獨設定時,以該設定為準。 如需提高團隊併發量,請聯絡官方。 -
同步 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)。 -
重試:收到 429 後,等待執行中的請求完成,並遵循
Retry-After回應標頭進行退避重試;收到 503 表示服務暫時無法使用,請稍後重試。 -
支援的平台: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 來自支援的平台且可公開存取。