How do I identify a Douyin video from a share link and continue to comments?
Fetch Douyin comments with the video’s aweme_id. With a v.douyin.com share link, first fetch the post details with douyin.app.v3.fetch_one_video_by_share_url, check the caption and author, and read the video ID from data.aweme_detail.aweme_id. A page’s modal_id only points to the video opened in a feed or profile; check the modal_id against the actual details.
For example, for a shared product demo, check the caption and creator before reading the installation questions in the comments. The saved detail response also gives the publication time and an engagement snapshot.
What does each input identify?
When a link contains two conflicting post identities, confirm the target post before fetching anything; do not silently choose one ID.
If you saved a creator profile and a post opened from the profile, keep the profile URL in the account column and the post’s modal_id in the candidate column. Confirm the aweme_id returned by the detail lookup, then read comments with the confirmed aweme_id.
Move from a link to comments
- Retrieve the details by passing
share_urltodata:douyin.app.v3.fetch_one_video_by_share_url, as in the share-link workflow. - Check the post and the author, and keep the original string at
data.aweme_detail.aweme_id. Save any detail response without usable details for review. - Prepare the first request for
data:douyin.app.v3.fetch_video_comments. Skip step 1 when the ID is already verified, and reuse a saved detail response when you have one.
To hand the task to an assistant with BeatAPI tools configured:
Confirm the post behind this share link and retain caption, author and original post ID. Then prepare comment reading. Use actual returned comments for installation questions, keeping excerpts and context, and state the observed scope.
The local script prepare_comments.py below turns a saved detail response into one comment request. Preparing the request does not retrieve comments; continue the analysis with the comment guide.
Turn a saved detail response into a first-page comment request
Save the script below as prepare_comments.py, then run python3 prepare_comments.py douyin-detail.json douyin-comment-1. prepare_comments.py makes no network calls and only creates a new directory. The script checks the action, status, request ID and original-string post ID, keeps the exact source bytes, and writes the ready-to-send JSON with the source hash.
Check the printed ID and the saved details against the post you intend. The recorded hash detects changes to the saved file; the hash does not prove that the share link resolved to the intended post. The script rejects a numeric JSON ID even when Python can represent the number, because an earlier numeric conversion may already have lost precision. The script does not pad zeroes or convert the number back to text.
When do I send the comment request, and what does it cost?
Detail and comment requests are billed separately; see current pricing. Count one detail request when a share link needs resolving, plus the comment pages you select. Reuse verified IDs or saved details; local preparation makes no network calls.
After confirming the target and budget, send the prepared comment-request.json file once:
Run the send command once: do not rerun the command into the same response files, and do not retry an error automatically. comment-request.json fixes count=20 and cursor=0, as the input contract of douyin.app.v3.fetch_video_comments specifies. prepare_comments.py prepares one first-page request file, not a full export, comment CSV, or complete reply set, because the current contract does not publish the comment output shape. Continue with the comment workflow from the saved response’s actual structure.
What if HTTP succeeds without aweme_detail?
prepare_comments.py stops before creating any request. Even when HTTP returns success, a share-link detail response can return data.filter_list instead of aweme_detail. Keep the raw response and request_id. Do not send an empty ID, substitute the author’s ID, or create a zero-engagement row: an HTTP success alone does not confirm that usable post details came back.
Share link to CSV · Douyin questions
prepare_comments.py validates saved detail responses locally against the documented douyin.app.v3.fetch_one_video_by_share_url output contract.
Do I need to pass a_bogus or X-Bogus from the browser?
No. To look up a Douyin post, send the post’s public share_url. To read comments, send the verified aweme_id, count, and cursor. Authenticate both requests with your BeatAPI Key, and leave browser signatures and cookies in the original client.
a_bogus and X-Bogus are web-request signatures that appear in older tools’ logs; MediaCrawler and f2 show how those open-source projects use a_bogus and X-Bogus. To move a task from an older tool, recover the public link of the intended post and prepare the request with the steps below. MediaCrawler client · f2 Douyin utilities
Move from a browser request to this workflow
- Identify the intended post; do not copy the browser’s internal API URL. Use a public share link for detail retrieval, or prepare the comment request directly when
aweme_idis already verified. - Keep provenance through the handoff: details → original-string
aweme_id→ comment JSON. Signatures, Cookies, author IDs, and API Keys are neveraweme_idvalues. - Send only the inputs the selected action declares. Do not add User-Agent fingerprints, session data, or undeclared parameters to imitate a browser; extra parameters are not guaranteed to be rejected before billing.
- When a request fails, read the HTTP status, the public error code, and
request_id; do not attribute every error to an expired signature.
Public inputs such as share_url and aweme_id do not guarantee access to private, deleted, or inaccessible posts, and third-party web algorithms can change. Open-source behavior notes are based on the public repositories linked above and the documented BeatAPI action contracts.
Is msToken my BeatAPI Key, post ID or pagination cursor?
No. In the MediaCrawler client, the web-request parameter msToken is read from the xmst value in browser localStorage. f2’s TokenManager handles msToken in a separate token-management implementation. Both repositories document open-source behavior rather than an official Douyin specification of token lifetime or endpoint requirements.
Neither BeatAPI action on this page defines an msToken input field. Send the public share_url to douyin.app.v3.fetch_one_video_by_share_url, and send the verified original aweme_id with count=20 and an integer cursor to douyin.app.v3.fetch_video_comments. Your BeatAPI Bearer Key authenticates your BeatAPI account, aweme_id selects the post, and cursor selects a comment page; none of the three replaces another. Do not append msToken, xmst, browser storage dumps, or Douyin cookies to a request or a support message.
If an existing browser-based tool reports a token problem, diagnose the browser tool’s session separately. A token problem in the old tool does not prove aweme_id is wrong, and refreshing a Douyin browser token does not fix BeatAPI’s invalid_api_key or an insufficient balance. Moving the task to BeatAPI means sending each action’s declared inputs instead of transplanting old browser state; the error table above separates those failure modes. A post that is visible only when logged in, or otherwise inaccessible, does not become accessible through a different request route.
For a support report, keep action, HTTP status, error.code, request_id, and collection time. Remove the Authorization header, cookies, token query strings, and unrelated response content before sharing the report. Use cursor=0 for the first page as specified in the contract, and take every later cursor from the previous response of douyin.app.v3.fetch_video_comments. Do not use msToken as a cursor, and do not assume another provider’s one-hour cursor lifetime.
Is ttwid a creator identifier, and must I copy ttwid from my browser?
No. In the f2 Douyin implementation, TokenManager.gen_ttwid reads ttwid from a response Cookie and raises an error when the Cookie is absent. f2’s implementation shows how one project handles ttwid; f2 is not an official Douyin specification for every endpoint, defines no universal expiration time, and does not show that ttwid identifies a logged-in person. Do not put ttwid into aweme_id, sec_uid, or the BeatAPI Authorization header.
Neither BeatAPI action on this page defines a browser Cookie or ttwid input. Troubleshoot the issue at its source:
A Cookie is not a password, but do not post a full Cookie header because a Cookie header can include unrelated login and session information. The share-link and comment workflow needs neither a ttwid generator nor an expiry-refresh job; other BeatAPI actions may declare different inputs.
Are verifyFp, fp and s_v_web_id always the same thing?
Not always. In the MediaCrawler detail-request code, the s_v_web_id Cookie value is copied into both the verifyFp and fp request parameters. In the f2 implementation, gen_s_v_web_id delegates to the same generator as gen_verify_fp. A shared generator does not mean two independent calls produce the same value, and neither repository defines an official protocol or validity period.
verifyFp, fp, and s_v_web_id are browser request and session parameters, not a post ID, a creator ID, or proof that someone completed verification. Neither douyin.app.v3.fetch_one_video_by_share_url nor douyin.app.v3.fetch_video_comments accepts verifyFp, fp, or s_v_web_id. Use the share-link or verified-aweme_id workflow above; do not move a Cookie jar, a fingerprint bundle, or a browser-internal URL into a BeatAPI data request.
If an older tool reports a browser security error, record the tool and the failing request family separately. Do not classify the browser error as a BeatAPI Key problem, a deleted video, or a successful zero-result collection. For an actual BeatAPI error, use the HTTP status, error, and request-ID table above. Generated fingerprint values and retry loops are not a documented fix; this workflow neither generates fingerprints nor bypasses challenges.

