如何透過 API 查看 TikTok 貼文的發佈狀態
TikTok 以非同步方式處理 API 發佈的貼文:發佈呼叫會回傳 share_id,再以該 ID 作為 publish_id 呼叫 GET /business/publish/status/,即可查看貼文進度。TikTok 下載檔案時狀態為 PROCESSING_DOWNLOAD;貼文通過審核並發佈後為 PUBLISH_COMPLETE;失敗時則為 FAILED,並附上 frame_rate_check_failed 等原因。
easyCoexistence 透過 publish_tiktok_post 發佈 TikTok 貼文,並以 get_tiktok_publish_status 追蹤每則貼文,你可以從 Claude、ChatGPT 或自己的程式碼使用,讓 AI 即時看到 TikTok 的狀態及任何失敗原因。
貼文 ID 在 PUBLISH_COMPLETE 後需時多久才會出現;若仍未見,TikTok 建議三分鐘後重試。
TikTok 對下載 1 GB 貼文檔案所需時間的一般估算;實際時間視乎檔案大小與網絡。
檔案上傳完成後,貼文通常最長多久會公開;人手審核可能需時更久。
下載逾時多久後,TikTok 會以 video_pull_failed 或 photo_pull_failed 令貼文失敗。
為何需要追蹤 TikTok 貼文?
因為 TikTok 在背景處理貼文。發佈呼叫會啟動一項任務,並即時回傳 share_id;之後 TikTok 從 URL 下載檔案、檢查格式、進行審核,再將貼文公開。即使發佈呼叫已成功,貼文仍可能失敗。
有哪些狀態?
GET /business/publish/status/ 需要帳戶的 business_id,並以 share_id 作為 publish_id,回傳以下四種狀態之一:
PROCESSING_DOWNLOAD:TikTok 正從 URL 下載內容。PUBLISH_COMPLETE:貼文已通過審核並發佈;公開可見後,post_ids會列出該貼文。- FAILED:發佈已停止,reason 說明原因。
SEND_TO_USER_INBOX:草稿已上傳,TikTok 已通知創作者的收件箱;此狀態只適用於草稿。
發佈需時多久?
TikTok 沒有固定時間。下載時間視乎檔案大小與網絡;TikTok 的一般估算是 1 GB 檔案需時 30 分鐘,上限為一小時。之後,貼文通常在 2 分鐘內公開,若需人手審核則較久;貼文 ID 最多可能再需 3 分鐘才會在狀態中顯示。
失敗原因代表甚麼?
reason 指出是甚麼令貼文停止。部分原因代表檔案必須修改,其他則代表重試可能成功:
file_format_check_failed、duration_check_failed、frame_rate_check_failed、picture_size_check_failed:檔案不符合格式規定,TikTok 將這些標記為不可重試。video_pull_failed、photo_pull_failed:TikTok 無法下載檔案,或未能在一小時內完成;待 URL 可公開存取後再重試。- internal:TikTok 部分服務暫時無法使用,可以重試。
spam_risk_too_many_posts、spam_risk、spam_risk_text:因發文數量、行為或貼文字幕內容,TikTok 停止了該貼文。auth_removed:處理期間,帳戶撤回了應用程式的存取權限;TikTok 建議不要重試。spam_risk_user_banned_from_posting:該帳戶已被封禁,不能再發佈新貼文。
貼文 ID 有甚麼用?
用來日後找回貼文。TikTok 的參考資料會將貼文 ID 放入 filters.video_ids 傳給 /business/video/list/,以讀取貼文的數據指標。至於留言呼叫,則從帳戶的影片列表取得貼文的 item_id,並作為 video_id 使用;easyCoexistence 的留言工具亦以此作為 post_id。
easyCoexistence 如何追蹤貼文?
publish_tiktok_post 會回傳 TikTok 的 share_id,並註明 TikTok 正在處理該貼文;get_tiktok_publish_status 接受該 share_id,並回傳 TikTok 目前的狀態,如有原因亦會一併列出。請你的 AI 過幾分鐘再查一次,不要即時查詢。
常見錯誤
- 未見結果便再次發佈。首次呼叫只是啟動任務,因此應先查看狀態,才再次發送貼文。
- PUBLISH_COMPLETE 但沒有 post_ids 便視為錯誤。貼文 ID 可能再需最多三分鐘,屆時再查一次即可。
- 格式失敗後用同一檔案重試。file_format_check_failed 及其他檢查失敗,都需要更正檔案。
- 下載期間使 URL 離線。TikTok 無法取得檔案時,會以 video_pull_failed 或 photo_pull_failed 令貼文失敗。
每個連接每月由 US$ 9 降至 US$ 0.75,連接越多單價越低,首 3 天免費。
常見問題
TikTok 的 share_id 是甚麼?
發佈任務的 ID,由影片及相片發佈端點回傳。它以 publish_id 的形式用於狀態查詢。
TikTok 發佈狀態有 Webhook 嗎?
有。透過 /business/webhook/update/ 並以 event_type VIDEO 訂閱的應用程式,會收到 TikTok 的貼文發佈事件,例如附有原因及 publish_id 的 post.publish.failed,取代重複查詢狀態。
已發佈的貼文為何未有貼文 ID?
TikTok 在 PUBLISH_COMPLETE 後最多需時三分鐘才回傳 post_ids,而且只會為公開可見的貼文回傳。
失敗的 TikTok 貼文可以重試嗎?
視乎原因而定。下載失敗及內部錯誤可以重試;格式、時長、幀率及圖片尺寸失敗,則需要更正檔案。
繼續閱讀
兩分鐘內連接您的第一個頻道。
無需等待平台審核。連接 WhatsApp、Instagram、TikTok 或其他頻道,然後請您的 AI 發佈貼文、回覆訊息或匯報數據,並看着它運作。
- 免費試用 3 天
- 隨時取消
- 只用官方 API
- 24/7 監察
驗證日期