Skip to content

Latest commit

 

History

History
158 lines (118 loc) · 8 KB

README.md

File metadata and controls

158 lines (118 loc) · 8 KB

okdata for Python

Social data for AI agents, paid per call: TikTok, YouTube, Instagram, X, Reddit, RedNote (Xiaohongshu), Douyin, WeChat (Official Accounts and Channels), Bilibili, Weibo, Kuaishou and more. 200+ endpoints on 17 platforms behind one key, as typed Python methods, plain HTTP, or a remote MCP server for Claude, Cursor and Codex. A call that fails costs nothing, and you need no platform accounts, cookies or QR logins. Every endpoint is a typed method generated from the okdata catalog, with its price in its docstring.

抖音数据 API · 小红书数据接口 · 公众号文章阅读数接口 · 星图 / 蒲公英达人数据 · 社媒数据 MCP。 中文说明 · 中文文档

pip install okdata          # Python 3.9+, one dependency (httpx)
export OKDATA_API_KEY=okd_...

No key yet? Sign up at okdata.online (中文:注册).

What you can read

Platform For example Per call or item
TikTok video search, comments, accounts, transcripts, TikTok Shop products, Creative Center ads from $0.002
YouTube, Instagram, Reddit, Telegram search, posts, comments, channels and accounts, transcripts from $0.002
X (Twitter) post search, replies, quotes, accounts, followers, lists, communities from $0.0001
Meta and Google ad libraries ads by keyword or advertiser from $0.004
Xiaohongshu / RedNote (小红书) note search, notes, comments, creators, PGY (蒲公英) creators, shop products and reviews from $0.02
Douyin (抖音) video search, comments and replies, plays and likes, the hot list, Xingtu (星图) creators with rates and audience from $0.002
WeChat (微信) Official Account (公众号) articles with reads and likes, Channels (视频号) videos and comments, WeChat Search from $0.015
Weibo (微博) the hot search list, post search, comments, accounts from $0.002
Bilibili (B站) video search, comments, uploader videos, the popular board from $0.002
Kuaishou (快手) video search, comments, accounts, the hot list from $0.002

Every endpoint with its parameters, fields and price: okdata.online/apis (中文:接口列表).

Use it from Claude, Cursor or Codex (MCP)

An agent can use the same endpoints without this SDK, through the remote MCP server at https://api.okdata.online/mcp (Streamable HTTP, header Authorization: Bearer <key>). In Claude Code:

claude mcp add --transport http --scope user okdata https://api.okdata.online/mcp \
  --header 'Authorization: Bearer ${OKDATA_API_KEY}'

npx okdata setup --client cursor (or codex, claude-code) writes the entry for you. The agent looks up an endpoint and its price for free; only the data call is charged. More clients: okdata.online/mcp.

中文

okdata 是给 AI 智能体和代码用的社媒数据接口,按次付费。一个 key 就能读抖音、小红书、公众号、视频号、B站、微博、快手, 以及 TikTok、X、YouTube、Instagram、Reddit 的公开数据:搜视频和笔记、批量拉评论、查星图和蒲公英达人、 拿公众号文章的阅读数和点赞数、看微博热搜和抖音热榜。可以用这个 Python SDK,也可以在 Claude、Cursor、Codex 里 接 MCP(上面那一条命令),或者直接发 HTTP 请求。调用失败不扣钱,不需要平台账号、Cookie,也不用扫码。 支付宝、微信、银行卡都能充值。

中文文档 · 接口和价格 · MCP 接入 · 注册

First call

The Playground's Python tab shows the raw HTTP request; with the SDK the same call is:

from okdata import OkData

ok = OkData()  # reads OKDATA_API_KEY; OkData("okd_...") works too
page = ok.douyin.videos.search(query="露营装备", sort="latest", max_price="0.05")
for row in page.items:
    print(row["id"], row["metrics"]["likes"], row["text"][:60])
print("cost: $" + page.cost)

Parameters are flat and named as in the API (query, id, url, cursor, ...). Every method also takes view (compact | standard | full, same price), fields (["id", "text"] or "id,text"), max_price (sent as X-Max-Price: a call that could cost more is refused before it runs, never charged), idempotency_key and timeout. Any endpoint also works by id: ok.call("weibo.trends.list"), including ids newer than your SDK version.

What comes back: Page (list endpoints: items, next_cursor, has_more), Item (one object: item) or Batch (ids=[...] on endpoints that take a list: items, missing). Each has cost, balance_after, request_id, result_status, replayed, warnings, meta and the raw envelope. Items are plain dicts, typed as TypedDicts (Post, Account, Comment, ...).

Paging within a budget

for page in ok.pages("douyin.videos.comments.list", id="7301234567890123456", max_pages=5, max_spend="0.01"):
    ...

items = ok.items("x.posts.search", query="claude code", max_items=200, max_spend="0.05")
rows = list(items)
print(items.spent, items.stop_reason)   # "0.03", "max_items" | "max_spend" | "end" | "balance" | "max_pages"

Each page is a separate, separately charged call. Before each page the pager adds what that page could cost at most (the endpoint's max_charge) and stops if the total would pass max_spend; each call also carries X-Max-Price set to what is left, so the server refuses (free) anything dearer.

Retries and idempotency

Every paid call gets an Idempotency-Key, reused by its retries, so a retry is never charged twice. Retries follow the error body: retry yes / same_key are retried (after retry_after_seconds when given; a wait longer than max_retry_delay raises instead), once gets one more try, no and after_fix are never retried. Defaults: max_retries=2, timeout=65 seconds per attempt.

Errors

from okdata import OkDataError

try:
    ok.x.posts.get(id="1850000000000000000")
except OkDataError as err:
    err.code, err.charged, err.retry, err.request_id   # branch on code, never on message
    err.message, err.message_zh, err.problems, err.param, err.reason, err.retry_after_seconds

charged is False for almost every error, True for a not_found the endpoint charges (amount says how much) and None when it is not known yet (a lost answer, settlement_unknown): look it up with ok.calls.get(err.request_id) or ok.calls.by_key(err.idempotency_key). A lost connection raises OkDataConnectionError (connection_error or client_timeout, charged=None). The codes are in okdata.ERROR_CODES and at https://okdata.online/docs/errors/.

Async

import asyncio
from okdata import AsyncOkData

async def main():
    async with AsyncOkData() as ok:
        page = await ok.weibo.trends.list()
        async for row in ok.items("douyin.videos.search", query="露营装备", max_spend="0.1"):
            print(row["id"])

asyncio.run(main())

Free routes

ok.catalog(), ok.status() (no key needed), ok.account() (balance, key limits, rate tier), ok.usage(group_by=["day", "capability"]), ok.calls.get(request_id), ok.calls.result(request_id, view="full") (a result kept 24 h, read again for free) and ok.calls.by_key(idempotency_key).

Options

OkData(api_key=None, *, base_url=None, timeout=65.0, max_retries=2, retry_base_delay=0.5, max_retry_delay=20.0, source=None, end_user=None, user_agent=None, http_client=None). base_url defaults to OKDATA_BASE_URL, then https://api.okdata.online. source and end_user are sent as X-Source and X-End-User for your usage figures; every call carries X-Entry: sdk.

MIT licensed.