Python SDK

ByCrawl 官方 Python SDK — 型別化回應、非同步支援、自動分頁，以及內建重試邏輯。

PyPI · GitHub · Python 3.10+

第一次使用 ByCrawl？請先參閱快速開始以建立帳號並取得 API 金鑰。

安裝

安裝 SDK


pip install bycrawl

設定 API 金鑰

Environment Variable


export BYCRAWL_API_KEY="sk_byc_..."


from bycrawl import ByCrawl
 
client = ByCrawl()  # picks up from BYCRAWL_API_KEY

請勿將 API 金鑰提交至版本控制系統。請使用環境變數或密鑰管理工具。

發送第一個請求


from bycrawl import ByCrawl
 
client = ByCrawl()
 
user = client.threads.get_user("zuck")
print(user.data.username)        # "zuck"
print(user.data.follower_count)  # 3200000
 
post = client.threads.get_post("DQt-ox3kdE4")
print(post.data.text)
print(post.data.stats.likes)

回應物件

每個 SDK 方法都會回傳一個 APIResponse[T] 物件，包含三個部分：


resp = client.threads.get_user("zuck")
 
# 1. 型別化資料 — IDE 中可完整自動補全
resp.data.username         # str
resp.data.follower_count   # int
resp.data.is_verified      # bool
 
# 2. 速率限制中繼資料
resp.rate_limit.remaining  # requests remaining in window
resp.rate_limit.reset      # reset timestamp
 
# 3. 點數用量
resp.credit.remaining      # credits left
resp.credit.used           # credits consumed by this request

.data 欄位依端點進行型別化，因此您的 IDE 可為每個欄位提供自動補全 — 無需猜測鍵名或手動解析原始 JSON。

平台

Threads X / Twitter Facebook Instagram Reddit TikTok LinkedIn YouTube Dcard Google Maps 104 Jobs

平台	命名空間
Threads	`client.threads`
X / Twitter	`client.x`
Facebook	`client.facebook`
Instagram	`client.instagram`
Reddit	`client.reddit`
TikTok	`client.tiktok`
LinkedIn	`client.linkedin`
YouTube	`client.youtube`
Dcard	`client.dcard`
Google Maps	`client.gmaps`
104 Jobs	`client.job104`

所有平台遵循相同的使用模式：


# User profile
user = client.threads.get_user("zuck")
user = client.x.get_user("elonmusk")
user = client.instagram.get_user("instagram")
 
# Single post
post = client.threads.get_post("DQt-ox3kdE4")
tweet = client.x.get_post("1234567890")
video = client.tiktok.get_video("7123456789")
 
# User posts
posts = client.facebook.get_user_posts("NASA")
posts = client.reddit.get_subreddit_posts("python", sort="hot")

常見用法

搜尋


# Search across platforms
results = client.threads.search_posts("AI")
jobs = client.linkedin.search_jobs("software engineer", location="Taiwan")
jobs = client.job104.search_jobs(q="Python工程師")

自動分頁

以 iter_ 為前綴的方法會回傳迭代器，自動處理基於游標的分頁：


for post in client.threads.iter_user_posts("zuck"):
    print(post.text)
 
for job in client.linkedin.iter_search_jobs("data scientist"):
    print(job.title, job.location)

迭代器採用惰性載入 — 只有在您開始消費結果時才會依需求取得各頁資料。在開始迭代之前不會載入任何資料。

可用的迭代器：

平台	方法
Threads	`iter_user_posts()`, `iter_user_replies()`
X	`iter_user_posts()`, `iter_search_posts()`
LinkedIn	`iter_company_jobs()`, `iter_search_jobs()`
TikTok	`iter_video_comments()`
104 Jobs	`iter_search_jobs()`

批次操作

一次取得多篇 Threads 貼文：


# Submit and wait (blocking)
result = client.threads.bulk_submit_and_wait(
    ["post_id_1", "post_id_2", "post_id_3"],
    poll_interval=2.0,  # seconds between status checks
    timeout=300.0,       # max wait time
)
for post in result.data:
    print(post.text)
 
# Or manage manually
job = client.threads.bulk_submit(["id1", "id2", "id3"])
status = client.threads.bulk_status(job.data.job_id)
results = client.threads.bulk_results(job.data.job_id)

非同步支援

所有方法皆有對應的非同步版本，透過 AsyncByCrawl 使用。API 完全相同 — 只需 await 呼叫，並對迭代器使用 async for。

Sync


from bycrawl import ByCrawl
 
client = ByCrawl()
 
user = client.threads.get_user("zuck")
print(user.data.username)
 
for post in client.threads.iter_user_posts("zuck"):
    print(post.text)

錯誤處理


from bycrawl import ByCrawl, NotFoundError, RateLimitError, AuthenticationError
 
client = ByCrawl()
 
try:
    post = client.threads.get_post("invalid_id")
except NotFoundError:
    print("Post not found")
except RateLimitError as e:
    print(f"Rate limited — retry after {e.retry_after}s")
except AuthenticationError:
    print("Invalid API key")

例外階層：

例外	HTTP 狀態碼	說明
`ByCrawlError`	—	基礎例外
`APIError`	any	HTTP API 錯誤（包含 `status_code`、`body`）
`AuthenticationError`	401	API 金鑰無效或缺失
`PermissionError`	403	權限不足
`NotFoundError`	404	找不到資源
`RateLimitError`	429	超出速率/點數限制（包含 `retry_after`）
`ServerError`	5xx	伺服器端錯誤
`TimeoutError`	—	請求逾時
`ConnectionError`	—	網路連線錯誤

設定


client = ByCrawl(
    api_key="sk_byc_...",                  # or BYCRAWL_API_KEY env var
    base_url="https://api.bycrawl.com",    # default
    timeout=60.0,                           # seconds, default 60
    max_retries=2,                          # auto-retry on 429/5xx, default 2
)

SDK 會自動對速率限制（429）和伺服器錯誤（5xx）進行重試，使用指數退避搭配隨機抖動，並遵循 Retry-After 標頭。

TikTok 搜尋、留言和使用者影片端點使用瀏覽器自動化，需要 20-40 秒。請將 timeout 設定為至少 60 秒。詳情請參閱已知限制。