跳到导航

想研究一个抖音博主的内容,怎么整理作品并选出值得细看的案例?

要整理抖音博主的作品,复制博主公开主页链接里 /user/ 后面的标识,作为 sec_user_id 传给 douyin.app.v3.fetch_user_post_videos 查作品列表。按返回的游标翻页,保存每一页原始响应,再用 export_creator_posts.py 导出 posts.csv;需要 Excel 时,用 posts_to_xlsx.py 把同一批材料转成 XLSX。

例如要整理一位家居博主上个月的收纳视频,先保留文案、发布时间、计数和作品 ID,再筛出真正展示安装过程的作品。交接时一并写明实际查到的日期、页数和停止原因。

先决定要看什么,再定取多少页

研究问题先看哪些材料继续研究的依据
近期内容方向和表达同一账号、明确观察窗口内的文案与作品人工归纳主题,保留原句,不让AI补视频口播。
哪些作品值得作为案例相关文案、发布时间及实际互动内容适配优先,结合作品年龄和观察时间,不只按总数挑。
发文节奏有没有变化已覆盖窗口中的作品时间先检查是否漏页、是否覆盖完整区间;少页不能证明减少发布。
合作前想核查表现目标作品清单与可比计数公开互动不替代完播率、报价、成交或归因证据。

先取一页,看作品是否真的与研究问题相关,再批准后续页数和成本。count 是单次请求上限,可能出现短页和重复;不要用 20×页数宣称取得了这么多不同作品。

拿到表格,哪些案例应该保留?

先读 coverage.json,确认成功页、去重后的作品数和停止原因,再看 posts.csv。人工在另存的审核工作表里给每个作品增加“保留/排除/待核、理由、希望研究的角度、下一步”;export_creator_posts.py 不做这些判断。

例如,假设一篇旧作品互动高,但与你的产品场景无关,可以排除;一篇近期教程互动一般,但讲清了关键步骤,可以保留。这个取舍不能证明旧作品差、教程会带来销售,也不能把较久作品的总数和新作品直接比成内容质量排名。

文案只说明描述里写了什么;播放地址、封面和时长不能证明有人看完了内容。aweme_type 保留原代码,不把所有对象都猜成普通视频。需要具体评论或单作品核查时,另选对应流程,并另定范围。

交付时让同事能回到原始证据

posts.csv 保留每个作品的首次观察,observations.jsonl 保留重复和后续变化,sources.json 和原文件帮助定位来源;同一 ID 的多次观察只算一个案例。缺失和 0 保持区别,发布时间和查询时间分开。

需要交付 Excel 时,用后面的本地转换器 posts_to_xlsx.py 保留长 ID。转换器把所有单元格存成文本,精确保留证据;要算数字,另建核对后的计算表,不把 ID 列转成数值。新导出不会继承你另外工作表里的编辑判断,保留旧审核副本,按作品 ID 核对。

最后附一段范围说明:哪个博主、为什么取样、实际页数和时间、哪些作品值得看、缺哪些数据,以及下一步要核实什么。没有覆盖的历史明确标出,不能把可见列表结束当成所有历史都已取回。

比如给同事交一张三月作品表:先用 coverage.json 看成功页和停止原因,再用 posts.csv 里实际取得的发布时间核对覆盖范围并筛出三月内容。如果只保存到三月中旬,就标「上半月待补」,把上次成功页和实际续页游标留给同事。合并后,用一条长 ID 抽查 Excel 是否保留了原值。

先复用列表,确有需要再查详情

已保存的作品页可以离线导出和重算,不再发起查询。作品列表已经返回播放等计数字段时直接保留,缺失仍留空;不为已返回的字段给每个作品额外买详情。只有新观察、补页或新问题需要更多证据时,才另外核对对应动作的合同和预算。

下面第 1–7 步是账号准备、分页、导出和 Excel 交付的完整操作。依据:已观察的列表合同和离线回归测试;没有采集示例账号。

1. 确定博主与页数预算

输入实际的 sec_user_id,不是数字 uid、昵称或视频 aweme_id。完整的 https://www.douyin.com/user/<sec_user_id> 主页链接里,/user/ 后的完整一段就是所需标识,复制时不带查询参数。短分享链接先打开到实际主页;不从短链 token 猜 ID,也不把整个 URL 当作 sec_user_id。

先取一页,确认账号和列。请求里的 count:20 是上限,短页或重复条目按实际记录计。计划 50 页就是最多 50 次列表请求,单价见 BeatAPI 价格页。已保存的页面可以离线重新导出。

作品列表把作品放在 data.aweme_list,计数放在 statistics,不是其他产品的统一对象;列表可以返回 play_count,缺失的播放数仍留空。不要为了列表已经返回的列,给每个作品再买一次详情。作品列表不能证明完播率、独立触达或投放归因。

2. 保存首页请求和响应

把下面的请求体保存为 request-1.json,替换成真实账号标识:

{"action":"douyin.app.v3.fetch_user_post_videos","params":{"sec_user_id":"<actual_sec_user_id>","max_cursor":0,"count":20,"sort_type":0,"channel":"normal"}}

确认价格和范围后,只发送一次:

mkdir douyin-page-1 && \
curl --fail-with-body -sS https://api.beatapi.io/v1/social-data/call \
-H "Authorization: Bearer $BEATAPI_API_KEY" \
-H 'Content-Type: application/json' \
--data-binary @request-1.json \
-D douyin-page-1/response.headers \
-o douyin-page-1/response.json

记录实际 HTTP 状态和带时区的查询时间;生成了 JSON 文件不代表请求成功。独立目录防止覆盖旧证据。这里要用完整的 Social Data 直接响应,不能用 AI 截断预览或字段投影代替。

3. 记录实际分页链

在页面目录旁保存 pages.json。下例展示格式;账号、HTTP 状态和时间都要换成真实值,并记录实际发送的参数,包括显式写出的默认值:

[{"action":"douyin.app.v3.fetch_user_post_videos","params":{"sec_user_id":"<actual_sec_user_id>","max_cursor":0,"count":20,"sort_type":0,"channel":"normal"},"http_status":200,"collected_at":"2026-11-17T08:00:00+08:00","response_file":"douyin-page-1/response.json"}]

之后每批准一页,就为保存的响应追加一条记录,账号、count、排序和 channel 保持不变。sort_type: 0 是最新,1 是最热。normal 渠道看不到近期作品时,可以改用 channel: lite,但切换渠道要另开一条从 cursor=0 开始的链,不能混进旧链,也不要自动付费探测备用渠道。

4. 已存页面转表,不再次请求

把下面的脚本保存为 export_creator_posts.py,执行 python3 export_creator_posts.py pages.json creator-export-1。export_creator_posts.py 单次最多接受 200 份已存页面,不发起任何网络请求。脚本把 author.sec_uid 与目标账号核对,保留原字符串 aweme_id,验证游标链,已有输出目录不会被覆盖。

import csv
import hashlib
import json
import sys
from datetime import datetime
from pathlib import Path
manifest_file, output = map(Path, sys.argv[1:])
pages = json.loads(manifest_file.read_text(encoding="utf-8"))
if not isinstance(pages, list) or not 1 <= len(pages) <= 200:
raise SystemExit("Use 1 to 200 saved-page entries")
action = "douyin.app.v3.fetch_user_post_videos"
base = None
expected_cursor = 0
seen_cursors = {0}
seen_requests = set()
seen_files = set()
observations, selected, sources = [], {}, []
last_time = None
next_request = None
stop = "saved_page_limit"
failure_info = None
def integer(value):
return type(value) is int and 0 <= value <= 9007199254740991
def count(value):
if value is None: return ""
if integer(value): return value
if isinstance(value, str) and value.isascii() and value.isdigit(): return int(value)
raise ValueError("Expected nonnegative safe integer count or original digit string")
for index, entry in enumerate(pages):
params = entry.get("params")
if entry.get("action") != action or not isinstance(params, dict) or set(params) != {"sec_user_id", "max_cursor", "count", "sort_type", "channel"}:
raise ValueError("Record all five original request parameters for this workflow")
uid = params["sec_user_id"]
if not isinstance(uid, str) or not uid.strip() or uid != uid.strip():
raise ValueError("Use the actual sec_user_id string, not uid, nickname or URL")
if type(params["count"]) is not int or params["count"] != 20 or type(params["sort_type"]) is not int or params["sort_type"] not in (0, 1) or params["channel"] not in ("normal", "lite"):
raise ValueError("Keep count=20 and a documented sort/channel")
if not integer(params["max_cursor"]) or params["max_cursor"] != expected_cursor:
raise ValueError("Cursor chain differs from the preceding saved response")
scope = {key: params[key] for key in ("sec_user_id", "count", "sort_type", "channel")}
if base is None: base = scope
if scope != base: raise ValueError("Do not mix accounts, sort orders or channels in a pagination chain")
stamp = datetime.fromisoformat(entry["collected_at"].replace("Z", "+00:00"))
if stamp.utcoffset() is None or (last_time is not None and stamp < last_time):
raise ValueError("Use nondecreasing actual observation times with timezone")
last_time = stamp
path = (manifest_file.parent / entry["response_file"]).resolve()
if path in seen_files: raise ValueError("Repeated response file")
seen_files.add(path)
raw = path.read_bytes()
response = json.loads(raw)
if not isinstance(response, dict): raise ValueError("Expected a JSON response object")
http = entry.get("http_status")
if type(http) is not int or not 100 <= http <= 599: raise ValueError("Record a valid HTTP status")
saved_name = f"raw-page-{index + 1:02d}.json"
digest = hashlib.sha256(raw).hexdigest()
sources.append((saved_name, raw, {"file": saved_name, "source_file": str(path), "sha256": digest,
"params": params, "collected_at": entry["collected_at"], "http_status": http}))
if http != 200 or response.get("status") != "succeeded":
error = response.get("error")
if response.get("status") not in (None, "failed") or not isinstance(error, dict) or not isinstance(error.get("code"), str) or not error["code"].strip():
raise ValueError("Unrecognized failure envelope; preserve the original response for diagnosis")
failure_info = {"http_status": http, "error_code": error["code"], "source_file": saved_name}
failed_request_id = error.get("request_id", response.get("request_id"))
if isinstance(failed_request_id, str) and failed_request_id.strip(): failure_info["request_id"] = failed_request_id
stop = "request_failure"
if index != len(pages) - 1: raise ValueError("Stop the manifest at its failed request")
break
if response.get("error") is not None: raise ValueError("Success envelope contains an error")
if response.get("action") != action or not isinstance(response.get("request_id"), str) or not response["request_id"].strip():
raise ValueError("Wrong action or missing request ID")
request_id = response["request_id"]
if request_id in seen_requests: raise ValueError("Repeated request ID is not another page")
seen_requests.add(request_id)
data = response.get("data")
if not isinstance(data, dict) or not isinstance(data.get("aweme_list"), list) or type(data.get("has_more")) is not int or data["has_more"] not in (0, 1):
raise ValueError("Expected aweme_list and numeric has_more=0/1")
items = data["aweme_list"]
for item in items:
if not isinstance(item, dict): raise ValueError("Unexpected post object")
identifier = item.get("aweme_id")
if not isinstance(identifier, str) or not identifier.isascii() or not identifier.isdigit():
raise ValueError("Keep the original string-encoded aweme_id")
author = item.get("author")
if not isinstance(author, dict) or author.get("sec_uid") != uid:
raise ValueError("Returned post author does not match the requested account")
stats = item.get("statistics")
if stats is None: stats = {}
if not isinstance(stats, dict): raise ValueError("Invalid statistics object")
created = item.get("create_time")
if created is not None and not integer(created): raise ValueError("Invalid publication timestamp")
desc = item.get("desc")
if desc is not None and not isinstance(desc, str): raise ValueError("Invalid caption")
row = {"aweme_id": identifier, "sec_user_id": uid, "caption": desc or "", "create_time_unix": created,
"share_url": item.get("share_url"), "aweme_type": item.get("aweme_type"),
**{key: count(stats.get(key)) for key in ("digg_count", "comment_count", "share_count", "collect_count", "play_count")},
"collected_at": entry["collected_at"], "request_id": request_id, "source_file": saved_name, "source_sha256": digest}
for field in ("share_url",):
if row[field] is not None and not isinstance(row[field], str): raise ValueError("Invalid share link")
if row["aweme_type"] is not None and not integer(row["aweme_type"]): raise ValueError("Invalid post type code")
observations.append({"aweme_id": identifier, "request_id": request_id, "source_file": saved_name, "collected_at": entry["collected_at"], "item": item})
if identifier not in selected: selected[identifier] = row
returned_cursor = data.get("max_cursor")
if data["has_more"] == 0: stop = "provider_end"
elif not items: stop = "empty_page_with_more"
elif not integer(returned_cursor): stop = "missing_or_unsafe_cursor"
elif returned_cursor in seen_cursors: stop = "repeated_cursor"
else:
stop = "saved_page_limit"
seen_cursors.add(returned_cursor)
expected_cursor = returned_cursor
next_request = {"action": action, "params": {**base, "max_cursor": returned_cursor}}
if stop != "saved_page_limit":
next_request = None
if index != len(pages) - 1: raise ValueError("Extra entries after a terminal or anomalous page")
break
if stop == "request_failure": next_request = None
output.mkdir(exist_ok=False)
columns = ["aweme_id", "sec_user_id", "caption", "create_time_unix", "share_url", "aweme_type", "digg_count", "comment_count", "share_count", "collect_count", "play_count", "collected_at", "request_id", "source_file", "source_sha256"]
with (output / "posts.csv").open("x", encoding="utf-8-sig", newline="") as handle:
writer = csv.DictWriter(handle, fieldnames=columns)
writer.writeheader()
for row in selected.values():
writer.writerow({key: ("'" + value if isinstance(value, str) and value.lstrip().startswith(("=", "+", "-", "@")) else value) for key, value in row.items()})
with (output / "observations.jsonl").open("x", encoding="utf-8") as handle:
for observation in observations: handle.write(json.dumps(observation, ensure_ascii=False) + "\n")
for name, raw, _ in sources: (output / name).write_bytes(raw)
(output / "sources.json").write_text(json.dumps([record for _, _, record in sources], ensure_ascii=False, indent=2), encoding="utf-8")
coverage = {"scope": base, "saved_responses": len(sources), "successful_pages": len(seen_requests), "observations": len(observations), "unique_posts": len(selected), "duplicate_observations": len(observations) - len(selected), "stop_reason": stop, "failure": failure_info, "all_historical_posts_collected": False, "policy": "first observation in CSV; all returned observations retained; no network calls"}
(output / "coverage.json").write_text(json.dumps(coverage, indent=2), encoding="utf-8")
if next_request: (output / "next-request.json").write_text(json.dumps(next_request, indent=2), encoding="utf-8")
print(json.dumps(coverage))

5. 根据报告决定是否继续

再请求下一页之前,先读 coverage.json,按其中的停止原因决定下一步:

  • saved_page_limit 且有 next-request.json:已存链末尾有可用的新游标。仅在批准的预算内,把 next-request.json 的完整 body 发送一次,另存响应目录,向 pages.json 追加实际记录,再导出到新的目录;旧页只在本地重读,不再付费。
  • provider_end:has_more=0,当前返回的列表结束;provider_end 不证明已删除或私密的历史已经取全。
  • repeated_cursor、empty_page_with_more、missing_or_unsafe_cursor:停止,核对已存的请求和响应;不自增游标,不重播首页。
  • request_failure:识别到带非空错误代码的网关失败。此前的有效观察照常导出,失败的原响应也保留,但不生成下一页请求建议。先处理错误,再另行确认是否重试。

成功响应结构损坏、作者不符、参数混用或游标链断裂时,脚本在创建导出目录前停止,原始已存文件仍可用于排查。200 页只是 export_creator_posts.py 的本地处理上限,不是 API 承诺,更不是查询 200 页的授权。

6. 核对后交付

posts.csv 按清单顺序保留每个 aweme_id 的首次观察;observations.jsonl 保存每个返回对象,包括后续的计数变化;sources.json 对应原文字节、SHA-256、原参数和查询时间。用覆盖计数区分跨页重复和不同作品。缺失计数留空,0 保留为 0,以公式符号开头的文案会做表格转义。

create_time_unix 是发布时间,collected_at 是记录的查询时间,两者不能互换。aweme_type 保留原代码,不把所有作品默认当成视频。原对象里的媒体链接可能过期;本流程不下载视频,不验证字幕,也不统计独立观看者。

分享前抽两行与原对象核对,确认作者,写明停止原因和不同作品数。一页只是样本,即使是 provider_end 也只代表可见的返回列表。调整表格展示时复用原文件,不用再付费。

分享链接指标 · 评论流程

主页链接与账号编号准备。

7. 生成 Excel 工作簿,不让长作品 ID 被改写

直接双击 CSV,表格软件可能把长 ID 识别成数字或日期,所以把 posts.csv 留作源文件。需要真正的 .xlsx 时,用下面的离线标准库转换器 posts_to_xlsx.py,它把每个单元格都存成文本,包括 aweme_id、计数、时间和看起来像网址的内容。转换器精确保留 CSV 值,修复不了导出前就已四舍五入的 ID;转换器不创建公式、宏、可点击超链接,也不发网络请求。

将代码保存为 posts_to_xlsx.py,运行:

python3 posts_to_xlsx.py creator-export-1/posts.csv creator-posts-review.xlsx

posts_to_xlsx.py 生成一个 Posts 工作表,冻结表头并提供筛选。最多接受 50,000 行数据、100 列、20 MiB 的源 CSV,这是离线安全边界,不是平台限制。只有有效表头的空导出会生成仅含表头的工作簿,不能据此声称采集成功;已有输出不会被覆盖。CSV 为防公式执行添加的单引号会原样保留,需要引用文案原句时,回到归档的原响应核对。

import csv, hashlib, io, json, pathlib, re, sys, zipfile
from xml.etree import ElementTree as ET
source, target = map(pathlib.Path, sys.argv[1:3])
raw = source.read_bytes()
if len(raw) > 20 * 1024 * 1024: raise ValueError('Use a CSV of at most 20 MiB')
rows = list(csv.reader(io.StringIO(raw.decode('utf-8-sig'), newline='')))
if not rows or not 1 <= len(rows[0]) <= 100 or len(rows) > 50001:
raise ValueError('Expected header, at most 100 columns and 50000 data rows')
if len(set(rows[0])) != len(rows[0]) or any(not x for x in rows[0]):
raise ValueError('Header names must be nonempty and distinct')
if 'aweme_id' not in rows[0]: raise ValueError('Expected the documented posts.csv with aweme_id')
for row in rows:
if len(row) != len(rows[0]): raise ValueError('Ragged CSV')
for cell in row:
if len(cell.encode('utf-16-le')) // 2 > 32767 or re.search(r'[\x00-\x08\x0b\x0c\x0e-\x1f\ufffe\uffff]', cell):
raise ValueError('Cell exceeds spreadsheet text limits or contains invalid XML characters')
ns = 'http://schemas.openxmlformats.org/spreadsheetml/2006/main'
def tag(name): return '{'+ns+'}'+name
def col(n):
out = ''
while n: n, r = divmod(n-1,26); out = chr(65+r)+out
return out
sheet = ET.Element(tag('worksheet'))
views = ET.SubElement(sheet,tag('sheetViews'))
view = ET.SubElement(views,tag('sheetView'),workbookViewId='0')
ET.SubElement(view,tag('pane'),ySplit='1',topLeftCell='A2',activePane='bottomLeft',state='frozen')
data = ET.SubElement(sheet,tag('sheetData'))
for number, row in enumerate(rows,1):
node=ET.SubElement(data,tag('row'),r=str(number))
for index, value in enumerate(row,1):
cell=ET.SubElement(node,tag('c'),r=col(index)+str(number),t='inlineStr')
text=ET.SubElement(ET.SubElement(cell,tag('is')),tag('t'))
text.set('{http://www.w3.org/XML/1998/namespace}space','preserve');text.text=re.sub(r'_(?=x[0-9A-Fa-f]{4}_)','_x005F_',value)
ET.SubElement(sheet,tag('autoFilter'),ref='A1:'+col(len(rows[0]))+str(len(rows)))
parts={
'[Content_Types].xml':'<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types"><Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/><Default Extension="xml" ContentType="application/xml"/><Override PartName="/xl/workbook.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml"/><Override PartName="/xl/worksheets/sheet1.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml"/></Types>',
'_rels/.rels':'<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"><Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="xl/workbook.xml"/></Relationships>',
'xl/workbook.xml':'<workbook xmlns="'+ns+'" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships"><sheets><sheet name="Posts" sheetId="1" r:id="rId1"/></sheets></workbook>',
'xl/_rels/workbook.xml.rels':'<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"><Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet" Target="worksheets/sheet1.xml"/></Relationships>',
'xl/worksheets/sheet1.xml':ET.tostring(sheet,encoding='utf-8',xml_declaration=True).replace(b'\r',b'&#13;')}
if target.suffix.lower() != '.xlsx': raise ValueError('Use an .xlsx output filename')
with target.open('xb') as handle:
with zipfile.ZipFile(handle,'w',compression=zipfile.ZIP_DEFLATED) as z:
for name, content in parts.items():z.writestr(name,content)
print(json.dumps({'file':str(target),'rows':len(rows)-1,'source_sha256':hashlib.sha256(raw).hexdigest(),'all_cells':'text','network_calls':0}))

按三项验收工作簿:

  1. 把输出行数和 posts.csv 对照。
  2. 抽查几个完整的 aweme_id 和对应文案。
  3. 确认真实的 0 和空计数仍有区别。

工作簿有意把计数也存成文本,不要假设 SUM 会正确求和。确实需要运算时,在确认单位、缺失和安全数值范围后另建计算表,不要把证据 ID 列转成数字。工作簿与 posts.csv、observations.jsonl、sources.json、coverage.json 和原始分页目录一起保留;打印的 SHA-256 用来识别源 CSV,不证明数据真实性。

工作簿只是已核验的博主作品导出的可移交视图;评论、关键词搜索、趋势指数和达人报价各有单独的流程和预算。依据:本地合成回归测试覆盖了包结构和文本值;在 Excel 或 Numbers 里打开工作簿尚未验收。包结构依据 Microsoft SpreadsheetML 说明。

把作品目录变成账号内容复盘

先定一个材料能回答的问题,例如“最近教程的开头是否更清楚”。把目录按教程、促销、日常内容分别标注,再挑同口径指标齐全、作品年龄相近的样本,算出本轮同组的中位数。高于和低于中位数的作品各选一两条,回到实际作品,列出可观察的区别,比如开头有没有展示成品。作品少或字段缺失时,写出实际样本数。

对同一作品的变化可接作品快照,用确实取得的两个时点对照。账号历史涨粉、发布或私有投放归因需各自有来源。交给助手时,要求按主题、样本和已确认指标给出发现,并附原作品、可能解释和下一轮可尝试的改动。