透過 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 則為您自己的程式碼提供其後各頁及其他欄位所需的權杖。
/business/video/list/ 每頁最多返回的貼文數;max_count 預設為 10。
cursor 的單位為 UTC Unix 時間戳,端點會返回在該時間之前發布的貼文。
請求中指定多個欄位時,必須包含預設欄位,否則可能出現錯誤。
每個已授權帳戶在此端點可進行的呼叫次數上限,與每個 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 權限:
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 的範例,已刪減至描述性欄位及數字計數:
{
"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,即使仍有更多貼文。
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 的貼文。經篩選的請求與其他請求採用相同欄位,因此一次呼叫即可返回少數已知貼文的最新數字。
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:
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 參數所示的時間到期,故需要時應重新取得。
- 在列表中尋找私人貼文。此端點只返回公開貼文。
每個連接每月 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 監察
驗證日期