Skip to navigation

How do I continue from a Douyin creator profile without mixing sec_uid, uid and handles?

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

InformationMeaning and next step
sec_uid after /user/ in the profile URLPass sec_uid as sec_user_id to douyin.web.handler_user_profile_v4 and douyin.app.v3.fetch_user_post_videos
Returned data.user.uidNumeric account identity; retain the original string and follow the next action’s contract
unique_id / short_idCustom handle or short identifier; store separately from uid
nicknameDisplay name for manual checks, not a replacement identifier
Xingtu creator identifierA 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. 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. 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:

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.

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 · Video IDs and short links · Delivery-author checks

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.