> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# How do I identify a Douyin video from a share link and continue to comments?

> Resolve a Douyin share link with douyin.app.v3.fetch_one_video_by_share_url, confirm data.aweme_detail.aweme_id, and prepare a first-page comment request without confusing account IDs, modal_id, or short-link tokens.

**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?

| Information                        | Use                                                                        |
| ---------------------------------- | -------------------------------------------------------------------------- |
| `aweme_id`                         | One post, retained as the original digit string                            |
| `/video/<id>` or `/note/<id>`      | A specific video/image post's long link                                    |
| `modal_id`                         | The post opened within a feed or profile; check for conflict with the path |
| A `v.douyin.com` link              | Input to share-detail retrieval; the short-link token is not the post ID   |
| Author uid/sec_uid or display name | Account information, not a video identifier                                |

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

1. Retrieve the details by passing `share_url` to `data:douyin.app.v3.fetch_one_video_by_share_url`, as in the [share-link workflow](/guides/douyin-share-snapshot).
2. 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.
3. 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](/guides/douyin-video-comments).

## 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.

```python
import hashlib
import json
import sys
from pathlib import Path

source, output = map(Path, sys.argv[1:])
raw = source.read_bytes()
response = json.loads(raw)
if not isinstance(response, dict) or response.get('status') != 'succeeded' or response.get('action') != 'douyin.app.v3.fetch_one_video_by_share_url' or response.get('error') is not None:
    raise ValueError('Expected a successful share-link detail response')
request_id = response.get('request_id')
if not isinstance(request_id, str) or not request_id.strip():
    raise ValueError('Missing source request_id')
data = response.get('data')
post = data.get('aweme_detail') if isinstance(data, dict) else None
if not isinstance(post, dict):
    raise ValueError('No aweme_detail; inspect the saved error/filter_list, do not query comments')
post_id = post.get('aweme_id')
if not isinstance(post_id, str) or not post_id.isascii() or not post_id.isdigit() or not int(post_id):
    raise ValueError('Use the original nonzero ASCII digit-string aweme_id; never stringify numeric IDs')
request = {'action': 'douyin.app.v3.fetch_video_comments', 'params': {'aweme_id': post_id, 'count': 20, 'cursor': 0}}
audit = {'source_file': str(source.resolve()), 'source_sha256': hashlib.sha256(raw).hexdigest(), 'detail_request_id': request_id, 'aweme_id': post_id, 'network_calls': 0, 'target_check': 'Compare this post ID and the saved detail with the intended post before sending'}
output.mkdir(parents=False, exist_ok=False)
(output / 'comment-request.json').write_text(json.dumps(request, ensure_ascii=False, indent=2) + '\n', encoding='utf-8')
(output / 'source.json').write_text(json.dumps(audit, ensure_ascii=False, indent=2) + '\n', encoding='utf-8')
(output / 'detail-response.json').write_bytes(raw)
print(post_id)
```

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](https://beatapi.io/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:

```bash
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 @douyin-comment-1/comment-request.json \
  -D douyin-comment-1/comment-response.headers \
  -o douyin-comment-1/comment-response.json
```

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](/guides/douyin-video-comments) 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](/guides/douyin-share-snapshot) · [Douyin questions](/faq/douyin)

`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](https://github.com/NanmiCoder/MediaCrawler/blob/main/media_platform/douyin/client.py) · [f2 Douyin utilities](https://github.com/Johnserf-Seed/f2/blob/main/f2/apps/douyin/utils.py)

### Move from a browser request to this workflow

1. 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_id` is already verified.
2. Keep provenance through the handoff: details → original-string `aweme_id` → comment JSON. Signatures, Cookies, author IDs, and API Keys are never `aweme_id` values.
3. 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.
4. When a request fails, read the HTTP status, the public error code, and `request_id`; do not attribute every error to an expired signature.

| Symptom                                               | Response in this workflow                                                                                              |
| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| 401 / invalid_api_key                                 | Check BeatAPI authentication; do not fetch Douyin Cookies or include the Key in a support ticket                       |
| 402                                                   | A balance/budget issue, not a missing a_bogus; do not recharge or repeat calls automatically                           |
| 400 / input error                                     | Check the current Inspect schema, post ID, and field types; a signature cannot repair a wrong object                   |
| 429                                                   | Read Retry-After and stop blind retries; do not cycle Cookies/accounts                                                 |
| 502 or platform unreachable                           | Preserve the error and request ID, then decide separately whether to retry; do not experiment by adding signatures     |
| Success without aweme_detail or an original string ID | `prepare_comments.py` refuses to build a comment request; do not infer zero comments or automatically buy another page |

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](https://github.com/NanmiCoder/MediaCrawler/blob/main/media_platform/douyin/client.py), the web-request parameter `msToken` is read from the `xmst` value in browser `localStorage`. [f2's TokenManager](https://github.com/Johnserf-Seed/f2/blob/main/f2/apps/douyin/utils.py) 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](https://github.com/Johnserf-Seed/f2/blob/main/f2/apps/douyin/utils.py), `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:

| Where the problem appears                    | What to check                                                                                                                                                                                |
| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| An old local scraper says ttwid is missing   | The scraper's own response and session configuration. The scraper's message does not indicate a BeatAPI request failure. Do not send the scraper's Cookie jar to BeatAPI support.            |
| A BeatAPI request returns 401                | The BeatAPI Key and Authorization header, not the browser's ttwid. Share a redacted error and request ID, not credentials.                                                                   |
| The share-link detail lacks a usable post ID | Stop the local handoff script and preserve the saved response. Adding a Cookie is not a documented recovery step.                                                                            |
| A working browser request is being migrated  | Transfer the intended public share URL or the verified original post ID, then send only the chosen action's inputs. Do not copy the browser request's Cookie, ttwid, or signed internal URL. |

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](https://github.com/NanmiCoder/MediaCrawler/blob/main/media_platform/douyin/client.py), the `s_v_web_id` Cookie value is copied into both the `verifyFp` and `fp` request parameters. In the [f2 implementation](https://github.com/Johnserf-Seed/f2/blob/main/f2/apps/douyin/utils.py), `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.