登入開始免費試用
easyCoexistence 官方 API

透過 API 列出 TikTok 帳戶的影片

TikTok 商業 API 以 GET /business/video/list/ 列出帳戶的公開貼文,由最新的開始,每頁最多 20 篇。指定要返回的欄位,例如 item_id、caption、share_url 及 video_views,並在 has_more 為 true 時以 cursor 逐頁讀取。filters.video_ids 可挑選特定貼文,而每個 item_id 即為留言相關呼叫所用的 ID。

easyCoexistence 透過 Claude、ChatGPT 或您自己的程式碼,以 list_social_posts 列出 TikTok 帳戶近期的貼文,包括每則貼文的 item_id、caption、連結及數據;get_social_credentials 則為您自己的程式碼提供其後各頁及其他欄位所需的權杖。

20

/business/video/list/ 每頁最多返回的貼文數;max_count 預設為 10。

Milliseconds

cursor 的單位為 UTC Unix 時間戳,端點會返回在該時間之前發布的貼文。

item_id

請求中指定多個欄位時,必須包含預設欄位,否則可能出現錯誤。

40/min

每個已授權帳戶在此端點可進行的呼叫次數上限,與每個 Accounts API 端點的規定相同。

此端點返回什麼?

帳戶的公開貼文,包括顯示於其個人檔案的影片、相片及文字貼文,以及 Only show in ads 影片,即只作為廣告播放、不會顯示於個人檔案的影片。media_type 用以分辨 VIDEO 與 PHOTO,後者涵蓋相片及文字貼文。被 TikTok 因違規(例如音樂版權)篩走的貼文,不會列入結果。

如何呼叫?

使用 GET 及 URL 參數:business_id、以 JSON 陣列表示的 fields,以及可選的 filters、cursor 與 max_count(預設為 10)。存取權杖放在 Access-Token 標頭中,開發者應用程式須在 TikTok Accounts 下取得 Get Account Media 權限:

List the latest posts
curl -G 'https://business-api.tiktok.com/open_api/v1.3/business/video/list/' \
  -H 'Access-Token: <ACCESS_TOKEN>' \
  --data-urlencode 'business_id=<OPEN_ID>' \
  --data-urlencode 'fields=["item_id","create_time","media_type","caption","share_url","thumbnail_url","video_views","likes","comments","shares"]' \
  --data-urlencode 'max_count=20'

哪些欄位描述貼文?

除數據外(由 video_views 至 impression_sources),列表還包括以下欄位,均屬 video.list 範圍:

  • item_id:貼文的 ID,供留言呼叫及 filters.video_ids 使用。
  • media_type:VIDEO,或 PHOTO(相片或文字貼文)。
  • is_ad:該貼文是否正用於廣告。
  • create_time:發布時間,以 UTC 的 Unix 秒數表示。
  • caption:貼文的描述,包括主題標籤。
  • share_url:可分享的連結,在手機與桌面上的行為不同。
  • embed_url:供其他網站使用的播放器連結,不能播放設定為 Friends 或 Only you 的貼文。
  • thumbnail_url:暫時性的預覽圖片,其到期時間在 x-expires 參數中。
  • video_duration:影片長度,以秒為單位,精確至小數點後三位。

一頁結果是什麼樣子?

videos 陣列,依 TikTok 返回的次序排列,另有 cursor(下一頁所用的值)及 has_more(表示是否還有下一頁)。create_time 以 Unix 秒數的字串形式返回。以下為 TikTok 的範例,已刪減至描述性欄位及數字計數:

A page from /business/video/list/
{
  "code": 0,
  "message": "OK",
  "request_id": "2021080307532501024502410704A7306F",
  "data": {
    "videos": [
      {
        "item_id": "6990565363377392901",
        "create_time": "1627617835",
        "caption": "little coco",
        "share_url": "https://www.tiktok.com/@feather_in_the_w1nd/video/6990565363377392901?utm_campaign=tt4d_open_api&utm_source=6979330045630218242",
        "likes": 10,
        "comments": 2,
        "shares": 0,
        "video_views": 1231
      }
    ],
    "cursor": 0,
    "has_more": false
  }
}

分頁如何運作?

以時間為準。cursor 預設為當下的毫秒時間,故首頁包含最新的貼文,每個回應都會返回下一次請求所用的 cursor。當 has_more 為 true 時傳送該值。若指定自訂時間戳,則列出該時間之前發布的貼文;此外,TikTok 的信任與安全規則可能令頁面的貼文少於 max_count,即使仍有更多貼文。

Every page, in Python
import json, requests

API = "https://business-api.tiktok.com/open_api/v1.3"

def all_posts(token: str, business_id: str, fields: list[str]):
    params = {"business_id": business_id, "fields": json.dumps(fields), "max_count": 20}
    while True:
        r = requests.get(f"{API}/business/video/list/", headers={"Access-Token": token},
                         params=params, timeout=30).json()
        if r["code"] != 0:
            raise RuntimeError(f"{r['code']}: {r['message']}")
        yield from r["data"].get("videos", [])
        if not r["data"].get("has_more"):
            return
        params["cursor"] = r["data"]["cursor"]

如何取得特定貼文?

透過 filters(一個 JSON 物件):video_ids 列出要返回的貼文 ID,例如來自發布狀態的 post_ids。ad_post_only 只可與 video_ids 一同使用,它只保留已授權給廣告主用於 Spark Ads 的貼文。經篩選的請求與其他請求採用相同欄位,因此一次呼叫即可返回少數已知貼文的最新數字。

The filters parameter
filters={"video_ids":["6995316737801538821","8015388216995316737"]}

適用哪些限制?

Accounts API 每個已授權帳戶在此端點每分鐘可呼叫 40 次;應用程式的 Accounts API 呼叫合計在基本級別每分鐘為 600 次,高於基本級別則為 1,000 次。描述性欄位為即時數據,數字通常延遲 24 至 48 小時,而貼文的數據在發布 365 日後停止更新。

easyCoexistence 如何列出影片?

使用 list_social_posts,它接受 account_id 及可選的 limit(TikTok 為 1 至 20)。它返回 TikTok 的第一頁:最近的貼文,包括 item_id、create_time、caption、share_url、thumbnail_url、video_views、likes、comments 與 shares,另加 cursor 及 has_more。其後各頁及其他欄位,則由你自己的程式碼取得,使用 get_social_credentials 提供的權杖與 business_id:

The next page from your own code
GET https://business-api.tiktok.com/open_api/v1.3/business/video/list/
  ?business_id=<BUSINESS_ID>
  &fields=["item_id","media_type","caption","embed_url"]
  &cursor=1793404800000
  &max_count=20
Access-Token: <ACCESS_TOKEN>

常見錯誤

  • 請求欄位時未包含 item_id。TikTok 的參考文件提醒,若請求指定多個欄位卻不含 item_id,可能會失敗。
  • 頁面不足 max_count 時便停止。TikTok 可能在 has_more 仍為 true 時返回少於 max_count 的貼文,因此應依循 has_more。
  • 把 thumbnail_url 存起來以備日後使用。這是暫時連結,會在 x-expires 參數所示的時間到期,故需要時應重新取得。
  • 在列表中尋找私人貼文。此端點只返回公開貼文。
使用 EasyCoexistence 完成這項設定

每個連接每月 US$ 9 至 US$ 0.75,連接越多越便宜,並提供首 3 日免費試用。

常見問題

一次可列出多少段 TikTok 影片?

每頁最多 20 篇,來自 /business/video/list/。max_count 設定每頁數量,預設為 10;如需更多,請依循 cursor。

TikTok API 也會列出相片貼文嗎?

會。/business/video/list/ 返回公開的影片、相片及文字貼文,media_type 可分辨 VIDEO 與 PHOTO。

TikTok 影片列表包括僅用於廣告的貼文嗎?

包括。/business/video/list/ 亦會返回 Only show in ads 影片,即只作為廣告播放、不會顯示於個人檔案的影片;is_ad 則表示該貼文是否正用於廣告。

為何某則 TikTok 貼文沒有出現在 API 列表中?

此端點只列出公開貼文,而 TikTok 會排除因違規(例如音樂版權)被篩走的貼文。

繼續閱讀

兩分鐘內連接您的第一個頻道。

無需等待平台審核。連接 WhatsApp、Instagram、TikTok 或其他頻道,然後請您的 AI 發佈貼文、回覆訊息或匯報數據,並看着它運作。

  • 免費試用 3 天
  • 隨時取消
  • 只用官方 API
  • 24/7 監察

驗證日期