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 是使用者名稱(不是暱稱),支援前導 @ 並保留點號。省略 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

  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 來自支援的平台且可公開存取。