> 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 continue from a Douyin creator profile without mixing sec_uid, uid and handles?

> Map Douyin profile URLs to sec_user_id for douyin.web.handler_user_profile_v4 and douyin.app.v3.fetch_user_post_videos, read data.user.uid as a string, and keep handles and Xingtu IDs separate.

To list a Douyin creator’s posts, extract the `sec_uid` segment after `/user/` from the creator’s profile URL and pass `sec_uid` as the `sec_user_id` parameter. To obtain the numeric account ID, read `data.user.uid` from the profile response. Use the displayed Douyin handle only for manual review. If you only have a numeric UID, start with `douyin.web.fetch_user_profile_by_uid` and verify any returned `sec_uid` before requesting posts.

For example, for a home-organization creator, confirm the account first, then use the creator’s post directory to select relevant tutorials. Keep `nickname`, `unique_id`, and `uid` in separate fields so later observations refer to the same account.

## Choose the identifier for the task

| Information                                 | Meaning and next step                                                                                              |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `sec_uid` after `/user/` in the profile URL | Pass `sec_uid` as `sec_user_id` to `douyin.web.handler_user_profile_v4` and `douyin.app.v3.fetch_user_post_videos` |
| Returned `data.user.uid`                    | Numeric account identity; retain the original string and follow the next action's contract                         |
| `unique_id` / `short_id`                    | Custom handle or short identifier; store separately from `uid`                                                     |
| `nickname`                                  | Display name for manual checks, not a replacement identifier                                                       |
| Xingtu creator identifier                   | A separate action's object, not automatically equal to `data.user.uid`                                             |

The profile output field is `sec_uid`, while the request input name is `sec_user_id`. Keep `sec_uid` and `sec_user_id` distinct instead of renaming every identifier to `id`, and do not calculate `uid` from `sec_uid`.

## Look up a uid from sec_uid, or start from a uid

With a verified `sec_uid`, call `douyin.web.handler_user_profile_v4`, confirm that `data.user.sec_uid` matches the requested account, and then read `data.user.uid`. With only a confirmed numeric `uid`, call `douyin.web.fetch_user_profile_by_uid` with `uid` as a string. Because the output schema of `douyin.web.fetch_user_profile_by_uid` is unconfirmed, verify and keep `sec_uid` if the response explicitly returns a matching value; otherwise, confirm the creator from a profile link or other primary material before requesting posts.

## When is a profile request needed?

With a verified `sec_uid` and a task that only needs the post list, go directly to the [creator directory](/guides/douyin-creator-post-export). To check the account’s `uid`, handle, and profile fields, request `data:douyin.web.handler_user_profile_v4` with `sec_user_id`.

The profile object lives at `data.user`. Compare the returned `data.user.sec_uid` with the requested `sec_user_id` before recording `uid`, `unique_id`, `short_id`, and `nickname`. Record a missing handle as unavailable. A shared display name is not evidence of the same account.

To hand the task to an assistant with BeatAPI tools configured:

> Use this verified profile as the starting point for creator research. Reuse sec_uid when listing posts; retrieve profile details only when needed and confirm the returned account matches. Keep the source URL and identifiers, then select home-organization tutorials to investigate.

Profile retrieval and post retrieval are billed as separate requests; see current [pricing](https://beatapi.io/pricing). The local helper `douyin_identity.py` below prepares a request and verifies a saved response; `douyin_identity.py` makes no network calls.

## Prepare the right request, then cross-check its saved response

`douyin_identity.py` only prepares and verifies local files. The `prepare` command reads a complete HTTPS profile URL. `prepare` does not resolve short links or search nicknames, and rejects video URLs, lookalike domains and numeric-uid paths. Query parameters and fragments are not sent to the API. A copied `/user/` segment that `prepare` accepts does not prove the account exists.

Save the script as `douyin_identity.py`:

```python
import hashlib,json,pathlib,re,sys
from urllib.parse import urlparse,unquote
mode=sys.argv[1]
if mode=="prepare":
    link=sys.argv[2];target=pathlib.Path(sys.argv[3]);url=urlparse(link)
    if url.scheme!="https" or url.hostname not in ("douyin.com","www.douyin.com") or url.username or url.password or url.port not in (None,443):raise ValueError("Use a public HTTPS Douyin profile URL")
    parts=[unquote(p) for p in url.path.strip('/').split('/')]
    if len(parts)!=2 or parts[0]!="user" or not re.fullmatch(r"[A-Za-z0-9_-]+",parts[1]) or parts[1].isdigit():raise ValueError("Expected /user/<copied sec_uid>, not a video, handle or numeric uid")
    sec=parts[1]
    body={"action":"douyin.web.handler_user_profile_v4","params":{"sec_user_id":sec}}
    target.mkdir();(target/"request.json").write_text(json.dumps(body,ensure_ascii=False,indent=2),encoding="utf-8")
    (target/"input-audit.json").write_text(json.dumps({"profile_url":"https://www.douyin.com/user/"+sec,"query_or_fragment_discarded":bool(url.query or url.fragment),"executed":False},ensure_ascii=False,indent=2),encoding="utf-8")
elif mode=="verify":
    request_file,raw_file,target=map(pathlib.Path,sys.argv[2:5]);request=json.loads(request_file.read_text(encoding="utf-8"))
    if request.get("action")!="douyin.web.handler_user_profile_v4" or set(request.get("params",{}))!={"sec_user_id"}:raise ValueError("Use the saved profile request")
    sec=request["params"]["sec_user_id"]
    if not isinstance(sec,str) or not sec or not re.fullmatch(r"[A-Za-z0-9_-]+",sec) or sec.isdigit():raise ValueError("Invalid expected sec_user_id")
    raw=raw_file.read_bytes();response=json.loads(raw)
    if not isinstance(response,dict) or response.get("status")!="succeeded" or response.get("action")!=request["action"] or response.get("error") is not None:raise ValueError("Expected successful profile response")
    rid=response.get("request_id")
    if not isinstance(rid,str) or not rid.strip():raise ValueError("Missing request ID")
    data=response.get("data");user=data.get("user") if isinstance(data,dict) else None
    if not isinstance(user,dict) or user.get("sec_uid")!=sec:raise ValueError("Profile sec_uid does not match the requested identity")
    values={}
    for field in ("uid","unique_id","short_id","nickname"):
        value=user.get(field)
        if value is not None and not isinstance(value,str):raise ValueError("Keep original string identity: "+field)
        if field=="uid" and value is not None and (not value.isascii() or not value.isdigit() or not any(c!="0" for c in value)):raise ValueError("uid must be an original nonzero ASCII digit string")
        values[field]=value
    identity={"sec_uid":sec,**values,"uid_available":values["uid"] is not None,"request_id":rid,"source_sha256":hashlib.sha256(raw).hexdigest(),"source_file":str(raw_file.resolve()),"scope":"One saved matching profile response; not a permanent alias or bidirectional ID-conversion guarantee"}
    post_request={"action":"douyin.app.v3.fetch_user_post_videos","params":{"sec_user_id":sec,"max_cursor":0,"count":20,"sort_type":0,"channel":"normal"}}
    target.mkdir();(target/"raw-profile.json").write_bytes(raw)
    (target/"identity.json").write_text(json.dumps(identity,ensure_ascii=False,indent=2),encoding="utf-8")
    (target/"creator-posts-request.json").write_text(json.dumps(post_request,ensure_ascii=False,indent=2),encoding="utf-8")
else:raise ValueError("Use prepare or verify mode")
print(str(target))
```

Run `python3 douyin_identity.py prepare 'REAL_HTTPS_PROFILE_URL' profile-request`. The new `profile-request` folder contains `request.json` and `input-audit.json` with `executed` set to false. Review the identity before approving the profile request. Submit only `request.json` as the API body, then save the actual response as `profile-call/response.json` together with the HTTP status. A failed response does not go into `verify` and does not trigger automatic identifier guesses.

```bash
mkdir profile-call &&
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 @profile-request/request.json \
  -D profile-call/headers.txt \
  -o profile-call/response.json
```

With a saved successful response, run `python3 douyin_identity.py verify profile-request/request.json profile-call/response.json identity-review`. The new `identity-review` folder contains `identity.json`, the exact `raw-profile.json` and a separately approvable `creator-posts-request.json`. `verify` checks the action, the `request_id` and an exact `data.user.sec_uid` match against the original request before recording uid and the other fields. A numeric uid must stay an original nonzero ASCII string; a missing uid stays null and is not filled from short_id.

## What do identity.json and creator-posts-request.json establish?

`identity.json` records `sec_uid`, `uid`, `unique_id`, `short_id`, `nickname`, and `source_sha256` from one matching profile response. Because a numeric `uid` can exceed JavaScript’s safe integer range, keep `uid` as the original string. If you only have a `uid`, an action that requires `sec_user_id` cannot convert `uid` back to `sec_uid`. Do not calculate an identifier, and do not treat nickname search results as a confirmed match.

`creator-posts-request.json` is an unexecuted first-page post request that uses the matched `sec_uid`; `creator-posts-request.json` collects neither posts nor comments. If you already have a verified `sec_uid`, skip the profile lookup workflow and use the creator-post guide directly. An empty custom handle stays empty: do not infer an account problem or substitute another ID. `source_sha256` verifies local file bytes; `source_sha256` does not prove a permanent account identity or the accuracy of the collection time.

[Creator-post export and pagination](/guides/douyin-creator-post-export) · [Video IDs and short links](/faq/douyin-video-id) · [Delivery-author checks](/guides/douyin-share-snapshot)

## Verify certification, live status and commerce capability separately

When you evaluate a live-stream collaboration, confirm the profile and save the returned `custom_verify` and `live_status` values with the collection time. Use the `custom_verify` description to help identify the account, and confirm the actual certification type separately. `live_status` describes the moment of observation only. Product-showcase presence and commerce permission require separate evidence: `douyin.web.handler_user_profile_v4` has no verified fixed fields for product-showcase presence or commerce permission.