Перейти к навигации

Save Douyin share-link details and engagement to CSV

To save a Douyin share link’s details and engagement to CSV, look up the share link with douyin.app.v3.fetch_one_video_by_share_url, then export one CSV row from the saved response with douyin_snapshot.py. The row keeps the video ID, caption, engagement counts and observation time. For completion rate, use a campaign or account report you can access for the same video.

1. Define the target and cost

Start with one real share link. Check the current price of data:douyin.app.v3.fetch_one_video_by_share_url with the free /v1/capabilities/inspect. The workflow makes one detail call and exports locally; the workflow does not fetch comments or download media.

2. Save the response

mkdir douyin-query-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' \
-d '{"action":"douyin.app.v3.fetch_one_video_by_share_url","params":{"share_url":"<share_url>"}}' \
-D douyin-query-1/headers.txt \
-o douyin-query-1/detail.json

Replace the placeholder link. If the HTTP request fails, stop and keep the error. Keep the raw JSON, and check the business status before parsing.

3. Convert the actual detail fields

Save the script below as douyin_snapshot.py. The script rejects failed or filtered responses, keeps zero separate from missing values, escapes text that starts with a formula character and only creates a new file.

import csv,hashlib,json,pathlib,sys
source,target=map(pathlib.Path,sys.argv[1:3])
source_bytes=source.read_bytes();digest=hashlib.sha256(source_bytes).hexdigest()
r=json.loads(source_bytes)
if not isinstance(r,dict) or r.get("error") is not None or r.get("status")!="succeeded" or r.get("action")!="douyin.app.v3.fetch_one_video_by_share_url":
raise ValueError("Expected successful share-link detail")
p=r.get("data",{}).get("aweme_detail")
if not isinstance(p,dict) or not p.get("aweme_id"):
raise ValueError("No usable aweme_detail; inspect filter_list and request_id")
if not isinstance(r.get("request_id"),str) or not r["request_id"].strip():
raise ValueError("Missing request_id")
if not isinstance(p["aweme_id"],str) or not p["aweme_id"].isascii() or not p["aweme_id"].isdigit() or not any(c!="0" for c in p["aweme_id"]):
raise ValueError("aweme_id must be a digit string")
for field in ("desc","share_url"):
if p.get(field) is not None and not isinstance(p[field],str):raise ValueError("Invalid text field: "+field)
if p.get("create_time") is not None and (type(p["create_time"]) is not int or not 0<=p["create_time"]<=9007199254740991):raise ValueError("Invalid publication timestamp")
stats=p.get("statistics")
if stats is None: stats={}
if not isinstance(stats,dict): raise ValueError("Invalid statistics")
for key in ["digg_count","comment_count","share_count","collect_count","play_count"]:
value=stats.get(key)
if value is not None and (type(value) is not int or not 0<=value<=9007199254740991):
raise ValueError("Invalid counter: "+key)
def cell(v):
if v is None:return ""
s=str(v)
return "'"+s if s.lstrip().startswith(("=","+","-","@")) else s
row=[p["aweme_id"],p.get("desc"),p.get("create_time"),p.get("share_url"),
stats.get("digg_count"),stats.get("comment_count"),stats.get("share_count"),
stats.get("collect_count"),stats.get("play_count"),r.get("request_id"),str(source.resolve()),digest]
with target.open("x",encoding="utf-8",newline="") as f:
w=csv.writer(f)
w.writerow(["aweme_id","caption","published_at","share_url","likes","comments","shares","collects","plays","request_id","source_file","source_sha256"])
w.writerow([cell(v) for v in row])
print(p["aweme_id"])

4. Run and verify

python3 douyin_snapshot.py douyin-query-1/detail.json douyin-snapshot-1.csv

Check that the printed aweme_id matches the target video. The counters come from statistics: digg_count, comment_count, share_count, collect_count and play_count. desc is the caption text, not subtitles. create_time is the publication time; record the collection time separately.

5. Keep meaningful snapshots

Save the next collection under a new filename. Compare only snapshots of the same aweme_id, and only the counters both snapshots contain. Plays are not unique viewers, and comment_count does not prove that every comment can be retrieved. Keep the request_id and the original response; do not replace filtered results with zeroes, and do not overwrite earlier snapshots.

6. Turn saved posts into a delivery-review sheet

For an agreed creator-post delivery, engagement numbers alone do not confirm the intended creator or the required caption. Build an auditable review sheet from the saved details instead of buying every post again. Create delivery-manifest.json with each expected video ID and the creator’s verified numeric uid, not the display name or sec_uid. collected_at is the original observation time, not the time you run the export.

Take the expected IDs from your agreed delivery roster or an independently verified creator record. Do not copy the returned author uid into the expected value to make the check pass. Replace every placeholder and the example time with your own recorded values.

[
{
"file": "douyin-query-1/detail.json",
"expected_aweme_id": "<verified_video_id>",
"expected_author_uid": "<verified_author_uid>",
"required_caption_phrase": "<agreed_caption_phrase>",
"collected_at": "2026-11-16T10:00:00+08:00"
}
]

Save the script below as review_delivery.py. The script reads local responses only, rejects a different video or a filtered detail, and leaves unknown metrics blank. The script reports an author mismatch or a missing caption phrase explicitly instead of accepting the delivery automatically.

import csv
import hashlib
import json
import sys
from datetime import datetime
from pathlib import Path
manifest, target = map(Path, sys.argv[1:3])
entries = json.loads(manifest.read_text(encoding="utf-8"))
if not isinstance(entries, list) or not entries:
raise SystemExit("Manifest must contain reviewed video records.")
rows, seen, requests = [], set(), set()
for entry in entries:
expected = entry.get("expected_aweme_id")
expected_author = entry.get("expected_author_uid")
phrase = entry.get("required_caption_phrase")
if not isinstance(expected, str) or not expected.isascii() or not expected.isdigit() or not any(c != "0" for c in expected) or expected in seen:
raise SystemExit("Each expected_aweme_id must be a unique digit string.")
if not isinstance(expected_author, str) or not expected_author.isascii() or not expected_author.isdigit() or not any(c != "0" for c in expected_author):
raise SystemExit("expected_author_uid must be a verified digit string, not nickname/sec_uid.")
if not isinstance(phrase, str) or not phrase.strip():
raise SystemExit("Set the exact caption phrase you want to check.")
collected = entry.get("collected_at")
if not isinstance(collected, str):
raise SystemExit("Record actual collected_at with timezone.")
moment = datetime.fromisoformat(collected.replace("Z", "+00:00"))
if moment.tzinfo is None:
raise SystemExit("collected_at requires timezone.")
source = manifest.parent / entry["file"]
source_bytes = source.read_bytes(); digest = hashlib.sha256(source_bytes).hexdigest()
raw = json.loads(source_bytes)
if not isinstance(raw, dict) or raw.get("error") is not None or raw.get("status") != "succeeded" or raw.get("action") != "douyin.app.v3.fetch_one_video_by_share_url":
raise SystemExit("Expected successful Douyin share-link detail.")
request_id = raw.get("request_id")
if not isinstance(request_id, str) or not request_id.strip() or request_id in requests:
raise SystemExit("Each observation needs a distinct request_id.")
post = raw.get("data", {}).get("aweme_detail")
if not isinstance(post, dict) or post.get("aweme_id") != expected:
raise SystemExit("Missing/filtered detail or aweme_id differs from the manifest.")
author = post.get("author")
if author is not None and not isinstance(author, dict):
raise SystemExit("Invalid author object.")
uid = (author or {}).get("uid")
if uid is not None and (not isinstance(uid, str) or not uid.isascii() or not uid.isdigit() or not any(c != "0" for c in uid)):
raise SystemExit("Invalid returned author uid.")
caption = post.get("desc")
if caption is not None and not isinstance(caption, str):
raise SystemExit("Invalid caption.")
if caption is not None and caption.strip() in {"[redacted]", "[redacted-depth]"}:
caption = None
author_check = "missing" if uid is None else ("match" if uid == expected_author else "mismatch")
phrase_check = "missing" if caption is None else ("present" if phrase in caption else "absent")
stats = post.get("statistics")
if stats is not None and not isinstance(stats, dict):
raise SystemExit("Invalid statistics.")
counts = []
for key in ["digg_count", "comment_count", "share_count", "collect_count", "play_count"]:
value = (stats or {}).get(key)
if value is not None and (type(value) is not int or not 0 <= value <= 9007199254740991):
raise SystemExit(f"Invalid counter: {key}")
counts.append(None if value is None else int(value))
rows.append([expected, expected_author, uid, author_check, phrase, phrase_check, caption,
*counts, collected, entry["file"], request_id, digest, "", ""])
seen.add(expected)
requests.add(request_id)
def cell(value):
if value is None:
return ""
value = str(value)
return "'" + value if value.lstrip().startswith(("=", "+", "-", "@")) else value
with target.open("x", encoding="utf-8", newline="") as output:
writer = csv.writer(output)
writer.writerow(["aweme_id", "expected_author_uid", "actual_author_uid", "author_check", "required_caption_phrase", "phrase_check", "caption", "likes", "comments", "shares", "collects", "plays", "collected_at", "source_file", "request_id", "source_sha256", "review_decision", "review_reason"])
writer.writerows([[cell(value) for value in row] for row in rows])
print(f"Wrote {len(rows)} delivery-review rows; no API calls made.")
python3 review_delivery.py delivery-manifest.json delivery-review.csv

Open the CSV with the ID columns imported as text. Check author_check and phrase_check, then fill in review_decision and review_reason. A caption can contain the required phrase while the video says something else, so watch the actual video before accepting brand claims, disclosure or product presentation. The review sheet is an operational check, not a legal compliance certification. The counters are observed totals, not campaign-attributed conversions or unique reach. An unavailable post stays an unresolved item, not a zero-performance delivery.

Input ID · Video URLs

Sources: nine historical backend output samples and the current sanitized rendering; both scripts are verified offline.

Both exports include source_sha256, the hash of the exact saved response bytes. Keep the original responses with the CSV and the manifest. A hash identifies a local file; a hash is not a platform signature or proof of collection time. Counter values must be safe nonnegative JSON integers: floats, booleans and unsafe bare integers stop the export instead of being rounded into a precise-looking result. IDs must be original nonzero ASCII-digit strings. An existing collection directory blocks another request, and the local export never refreshes a post.

Review plays and completion separately

For a tutorial retention review, fix the set of works and the observation window. Record plays when the regular snapshot returns statistics.play_count. For a Xingtu video report, pass the confirmed report item identifier as item_id to douyin.xingtu_v2.get_item_report_detail. The report’s fixed completion field, unit and general coverage are unconfirmed, so record a completion value only when a report provides the metric and the metric’s definition, together with the original value, window and source.

For example, if both tutorials have play counts and only one tutorial has a verified completion rate, compare plays and leave the other completion cell blank. Once both reports are available, align the dates and definitions. Use the lower reported completion to decide what to inspect, such as whether the introduction states the purpose or whether the demonstration has long pauses.