微博账号发帖研究 API 教程 | SandBase
用一次请求读取已知微博账号资料或一页普通帖子,校验响应、明确调用预算,并保留注明日期的原创帖历史研究证据。

研究微博账号,先把问题缩小:你是想确认一个已知账号的资料,还是想看看它的一页微博?这两个任务用不同的端点,返回的业务结构也不同。先把一次请求接稳,才能分清“确实没有结果”和“调用失败”,再决定要不要扩展分析。
本次 2026-11-08 修订通过免费 inspect 和公开响应参考核对两种首请求,没有执行付费业务调用。原文 2026-10-01 UTC 的真实账号实验、run ID 和精简 JSON 仍保留在后半部分;原创微博翻页、详情和评论链路没有重新实测。更多端点见微博公开数据 API 总览;热搜监测属于另一个任务。
先说结论
- 已知数字 UID 或个人主页自定义名称:调用一次
user-info,两个标识只传一个。- 已知 UID,想看账号微博:调用一次
user-posts,明确传page: 1、feature: 0,不传since_id。- 只读取已完成响应里的
outputs[0].data;资料检查user,微博检查整数ok: 1和data.list。- 普通时间线可能包含转发。一页内容不等于原创列表,也不等于完整历史。
先选一个任务
| 已有信息和问题 | 端点 | 本例输入 |
|---|---|---|
| 已知数字 UID,读取资料 | User info | 只传 uid |
| 已知主页里的自定义名称 | 同一个 user-info 端点 | 只传 custom |
| 已知 UID,读取一页微博 | User posts | uid、page: 1、feature: 0 |
昵称不一定是 custom,同名也不能证明就是目标账号。如果手里只有品牌名,应先确认身份;下面的代码不会搜索后自动选第一项。UID 保持字符串,避免客户端把大数字舍入。资料 schema 虽然没有把两个字段列为必填,但描述要求二选一,不要把两个都发过去。
帖子 schema 描述 page 默认 1、feature 默认 0,本例明确写入请求;since_id 描述为下一页标识,所以首页省略。函数不会继续翻页、查详情、抽评论或调用模型。普通时间线可能包含置顶和转发,不能把返回的第一项直接叫作“最新原创微博”。
已有 Key、已连接 Agent、新项目分别怎么接
已有 Key 的项目,把它保存在本地环境变量 SANDBASE_API_KEY,并在项目的 Python 环境安装 requests。不要把密钥贴进聊天、示例文件、日志或代码仓库。替换已确认的账号标识后,只运行一次。
如果 Agent 已连接 SandBase,就让它检查选定端点并复用连接,不必再创建一套项目或遍历整个目录。任务可以说清楚:“读取这个 UID 的资料一次,保留缺失字段,不自动查帖子;失败就报告错误,不拼一个空账号。”
新项目可以把setup skill和Markdown quickstart交给 Agent,再说明已知标识和要做的单个任务。人工快速入门解释账号和密钥配置。创建 Key 只是接入准备,不能证明账号读取成功,也不能证明免费额度还有余额。
一次请求的完整 Python 示例
数字字符串、自定义名称检查属于本例的输入保护,不代表账号存在,也不是微博用户名规则的完整定义。资料对象非空是本例的完整性要求;其余可选字段仍可以缺失。
import os
import re
import requests
def first_request(task, *, uid=None, custom=None):
if task not in ("profile", "posts"):
raise ValueError("Choose profile or posts")
if task == "profile":
if (uid is None) == (custom is None):
raise ValueError("Provide exactly one of uid or custom")
elif uid is None or custom is not None:
raise ValueError("Posts require uid only")
if uid is not None:
if not isinstance(uid, str) or not re.fullmatch(r"[0-9]+", uid):
raise ValueError("uid must be a numeric ID string")
params = {"uid": uid}
else:
if not isinstance(custom, str) or not custom.strip():
raise ValueError("custom must be a nonempty username")
value = custom.strip()
if "://" in value or "/" in value or any(c.isspace() for c in value):
raise ValueError("Provide the custom username, not a URL")
params = {"custom": value}
endpoint = "user-info" if task == "profile" else "user-posts"
if task == "posts":
params.update(page=1, feature=0)
key = os.environ.get("SANDBASE_API_KEY", "").strip()
if not key:
raise ValueError("Set SANDBASE_API_KEY locally")
try:
response = requests.post(
f"https://api.sandbase.ai/v1/api/weibo/web-v2/{endpoint}",
headers={"Authorization": f"Bearer {key}"},
json=params, timeout=(10, 90), allow_redirects=False,
)
if not 200 <= response.status_code < 300:
raise RuntimeError(f"HTTP {response.status_code}; no retry performed")
body = response.json()
except ValueError:
raise RuntimeError("Response was not valid JSON") from None
except requests.RequestException:
raise RuntimeError("Network request failed; no retry performed") from None
if not isinstance(body, dict) or body.get("status") != "completed":
raise RuntimeError("Request did not complete")
outputs = body.get("outputs")
if not isinstance(outputs, list) or not outputs or not isinstance(outputs[0], dict):
raise RuntimeError("Missing documented outputs[0].data")
payload = outputs[0].get("data")
if not isinstance(payload, dict):
raise RuntimeError("Missing business payload object")
if task == "profile":
if not isinstance(payload.get("user"), dict) or not payload["user"]:
raise RuntimeError("Missing profile user object")
else:
if type(payload.get("ok")) is not int or payload["ok"] != 1:
raise RuntimeError("Posts business request did not succeed")
data = payload.get("data")
if not isinstance(data, dict) or not isinstance(data.get("list"), list):
raise RuntimeError("Missing posts data.list array")
if any(not isinstance(item, dict) for item in data["list"]):
raise RuntimeError("Malformed post item")
return payload
if __name__ == "__main__":
result = first_request("profile", uid="1222135407")
print(result["user"].get("screen_name"))默认只读资料。要看微博,替换最后两行,分别写 result = first_request("posts", uid="1222135407") 和 print(len(result["data"]["list"]))。要用自定义名称,就把调用替换为 first_request("profile", custom="shuqi")。这是三种选择,不是要依次执行的三个步骤。
默认 UID 来自旧文的公开账号实验,shuqi 来自当前资料 schema。本次没有重新执行这些请求。公开资料 README 的历史示例同时传过 uid 和 custom,只能作为响应结构参考,不能当作本例二选一请求刚刚成功的证据。
两层成功都要检查
HTTP 返回了内容,不等于业务成功。重定向、鉴权或权限问题、额度或支付问题、服务错误都会让示例停止;超时和非法 JSON 也会报错。代码不会自动重发可能计费的操作,先看清失败原因,再决定是否重试。
SandBase 信封必须是 completed,且 outputs[0].data 为对象。不再兼容旧文优先读取顶层 output 的做法。资料参考的结构是 user 对象,本例没有给它强加一个并不存在于参考中的 ok: 1 条件。帖子成功参考则明确有整数 ok: 1、data 对象和对象数组 list,因此按这个结构验证;Python 的布尔 True 也不能冒充整数 1。合法空数组与缺失数组是两回事。
当前帖子 saved example 有一个容易误抄的陷阱:输入是 uid: "example",保存的响应外层出现 code: 200,内层却是 ok: 0 的失败结果。不要照抄这个无效 UID,不要把保存示例说成成功案例,也不要用外层 200 判断业务成功。本例采用数字 UID 契约,并拒绝这种失败结构。
不把未知补成零,不把一页当成全量
资料里没有 followers_count,表示未知;明确返回数字 0,才保留 0。认证标志为 false 和没有认证字段也要区分。昵称、认证说明可供人工核对身份,但不会自动选出你心里的目标账号。
公开参考里有头像 URL,保存地址不代表图片仍可访问;示例不下载媒体。部分参考字符串已被截断,也不能拿去当完整下载链接。历史总互动数是带逗号的字符串,转换失败或字段缺失时,不应默默填零后参与排序。
帖子先保留原始结构和采集来源,再设计研究表格。一页中可能有转发、置顶和长文预览,点赞或评论数也不能直接代表触达、成交或推广效果。缺少联合发布标志,不能证明没有商业合作。当前流程在这里停止,没有自动拉全文、跨账号排名或情绪总结。
费用和调用次数
2026-11-08 免费 inspect 显示,这两个选定端点的基础价格都是 $0.001/次,都符合组织共享的每日 100 次合资格 API 调用额度条件,在 UTC 00:00 重置。资格不是剩余额度查询,本次没有查看账户余额、没有测量实际扣费,不能承诺这一次一定免费。
选择资料或帖子示例,只发一次请求。如果另行决定两者都执行,就是两次,按基础价估算 $0.002,再考虑实际额度适用情况;默认代码并没有这么做。翻页、重试、详情都要单独计入预算。下面旧实验的七次调用,不是现在的首次接入成本。
旧文保留的目录截图:52 个端点与 Free Week 标识只描述当时画面,不代表当前总数或今天的剩余额度。当前选定端点价格另行核对;代码使用上文的 POST Model API 路径。
历史实验:2026-10-01,不是当前自动链路
保留的封面表达旧的搜索、排序、评论研究思路,不是本次验证可用的整条链路,也不是单次请求函数的产出。
当时搜索「中国国家地理」返回 20 个候选(run 4a509105-eb13-4513-bc6b-9e515167d4c7),主账号旁边还有商店、媒体中心等相关账号。旧函数优先取同名项,否则取第一项;这个规则不能可靠确认身份,所以不再放进当前可执行流程。
搜索的 fans: 1167 与资料里的 11,677,520 粉丝("1167.8万")不一致;另一账号搜索显示 fans: 1,而显示量级约为 1.58 亿。这些现象提示显示单位可能丢失,不是可通用的换算公式。资料 run 59d3b350-2227-49e1-bb25-1790a06950cb 保留的原始精简 JSON 如下:
{
"user": {
"idstr": "1222135407",
"screen_name": "中国国家地理",
"followers_count": 11677520,
"followers_count_str": "1167.8万",
"friends_count": 373,
"statuses_count": 28394,
"verified": true,
"verified_reason": "《中国国家地理》官方微博",
"location": "北京",
"status_total_counter": {
"repost_cnt": "3,130,409",
"comment_cnt": "1,820,565",
"like_cnt": "7,438,106",
"total_cnt_format": "1238.9万"
}
}
}带逗号的互动总数是当时的值,不是本次更新测出的数字。旧的 user-basic-info 轻量查询没有返回数值粉丝量,也不能据此保证两个端点现在始终有哪些字段。
原创帖实验使用 UID 1222135407:第一页 47 条(run cc08c1c1-9d06-4453-b0b6-35d44d04f1bb),第二页 50 条(run 2b5b4795-95ec-4180-96bc-ee397f16ed4a),没有重叠,约覆盖四周。当时响应没出现 since_id 或 has_more;两次 data.total 分别为 27,299、27,807,也不等于资料中的发帖总数。
那次成功不能解决今天的原创帖输入矛盾:当前 schema 描述说初始 since_id 要从 user-posts 获取,README Notes 却谈后续翻页,其 cURL 又省略该字段。本轮保留这个未确认问题,改用普通 user-posts 做首页示例,不猜 token,也不偷偷补一次前置请求。旧普通时间线观察(run 16f18948-183c-446d-bbb3-d74731720f4e)确实带过 since_id,但这不是本次续页测试。
历史原创帖参数参考。当前初始 since_id 的说明仍有歧义,2026-10-01 的页码调用成功不能当作新的翻页保证。
97 条历史原创帖中,一条联合旅行推广有 6,254 转发、692 评论、6,879 点赞,下一名转发为 384;仅该推广带有 cooperate_info。旧代码把排除它后的结果叫作“自然内容排名”,但缺少这个字段不能证明没有赞助。isAd 在包括日常问候的 37 条记录里为 true,因此当时也不能拿它稳定识别广告。
67 条带长文标志。推广帖列表预览 147 字,详情 run fff2fd24-3225-4ba1-921c-71f54cd4fb72 的 longText.content 为 238 字,还返回约 594 万阅读量。这些都是旧观察,本次没有重验详情。历史上一次 TLS 重置后重试成功,也不是把自动重试写进新付费流程的理由。
历史 post-detail 参考,显示 id 和长文选项;本轮没有调用或复验该端点。
评论 run f62a40cf-d18e-4f6f-b90b-c1c2b30b0f71、5664ad51-897d-4e17-8ef4-052a8f70e2d8 各返回 20 条不同评论,第二次把返回的数字 max_id 转成字符串传入。两页显示 total_number: 692,但更早的一次第二页没有新增;“已加载全部评论”字样也曾与后续结果并存。这些现象提醒我们不能凭提示语认定完整,更不是新的重试规则。样本里最高赞评论为 17 赞,旧流程主动丢弃了评论者身份。
历史 post-comments 参考,包含 count、id、max_id;本次没有重新验证评论续页或端点可用性。
旧组装流程计划七次端点调用:搜索、资料、两页原创帖、详情、两页评论,尚未计入重试。每种语言的八段原 Python 均逐字保存在历史代码归档,并记录哈希。其中包含旧双信封、自动重试、自动选账号和缺值填零;归档用于审计,不是现行接入代码。
常见问题
需要微博登录吗? 这些公开读取用 SandBase Key 鉴权,不授权发帖,也不提供私密或仅粉丝可见的数据。管理账号应使用合适的官方授权路线。
这个帖子请求只返回原创吗?
不是。user-posts 是普通时间线,可能带转发。原创专用端点因初始游标说明有歧义,目前只保留旧实验记录。
能一直翻到全部历史吗? 当前示例只查第一页。一页结果与历史两页实验,都不能证明现在能完整翻页、保持顺序或穷尽所有内容。
可以直接交给 Agent 吗? 可以给它 setup skill、已知标识和一个具体任务,要求返回校验后的数据及未知字段,不自动继续调用。看完首个结果,再决定是否扩大范围。
收个尾
从已经确认的账号信息出发,选一个请求,同时检查信封与业务结构。历史实验保留其价值,也保留日期和边界。打开 user-info 或 user-posts,按选定任务使用上面的示例即可。
2026 年 SandBase Weibo 枢纽的标价对比,见 2026 年最佳 Weibo API:价格对比。
觉得有用?分享给更多人