适用场景抖音用户公开信息 API 适用于需要批量或定期获取用户主页公开数据的场景例如创作者数据分析抓取头部达人的粉丝数、获赞数、作品数用于内容策略对照。自动化监控定时拉取关键账号的粉丝变化辅助运营决策。竞品追踪在合法合规前提下观察同赛道账号的活跃度与影响力。内容推荐系统作为特征输入判断用户量级。该接口仅返回用户公开可见的信息不涉及隐私数据且无需抖音官方 OAuth 授权只需 API Key 即可使用接入维护复杂度极低。接口能力边界输入抖音用户主页链接支持v.douyin.com短链如https://v.douyin.com/xxxxx/或douyin.com/user/长链如https://www.douyin.com/user/MS4wLjABAAAA...。接口会自动展开短链无需开发者自行处理重定向。输出JSON 格式包含nickname昵称、avatar头像 URL、signature个人签名、aweme_count作品数、follower_count粉丝数、following_count关注数、total_favorited获赞总数等字段。性能限制QPS每秒查询数为 5即单 API Key 下每秒最多发起 5 次请求。若频繁调用超过限制可能收到 429 状态码。数据时效性返回数据为调用时刻的公开快照非实时流式数据延迟通常在秒级以内。文档未给出具体 SLA生产环境需注意缓存策略。鉴权与参数鉴权方式所有请求必须在 HTTP 头部携带X-API-Key字段值为申请的 API 密钥。密钥需要向 API 提供商获取具体申请方式请参考官方文档。示例X-API-Key: your_api_key_hereQuery 参数参数名类型必填说明urlstring是抖音用户主页链接。支持短链v.douyin.com或长链douyin.com/user/注意url参数必须经过 URL 编码尤其是当链接包含特殊字符时但在 curl 命令中通常交给 shell 处理或使用--data-urlencode配合 GET 请求。更稳妥的方式是在代码中显式编码。curl 请求示例以下是一个可直接复制的 GET 请求使用环境变量APIZERO_API_KEY存储密钥。执行前请确保已设置该变量或将$APIZERO_API_KEY替换为实际值curl -sS \ -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/douyin-user?urlhttps%3A%2F%2Fv.douyin.com%2Fabcdef%2F若使用短链且未编码许多 shell 会自动处理但建议手动编码以避免歧义。例如原始 URL 为https://v.douyin.com/abcdef/编码后为https%3A%2F%2Fv.douyin.com%2Fabcdef%2F。也可写成带引号的形式让 curl 自动处理但注意 shell 可能对等字符做特殊解释这里参数只有url一个问题不大。验证请求返回状态码 200 且 body 中code为 0 表示成功否则根据msg和status排查。返回字段解读下面是一个典型的成功响应已格式化{ code: 0, data: { aweme_count: 123, follower_count: 9999, following_count: 520, nickname: 张三, avatar: https://p3-pc.douyinpic.com/aweme/100x100/..., signature: 记录生活, total_favorited: 100000, uid: MS4wLjAB..., sec_uid: MS4wLjAB... }, msg: 成功 }字段类型含义备注codeint业务状态码0 表示成功非 0 需根据 msg 处理msgstring状态描述成功时为“成功”data.nicknamestring用户昵称可能为空字符串data.avatarstring头像 URL一般为 100x100可访问但可能过期data.signaturestring个人签名无签名时为空data.aweme_countint作品数含图文、视频整数data.follower_countint粉丝数整数data.following_countint关注数整数data.total_favoritedint获赞总数整数data.uidstring用户唯一 ID可用于后续关联data.sec_uidstring安全 UID部分场景需用此 ID注意文档示例中仅展示了部分字段实际响应可能包含更多如short_id、unique_id等请以实际响应为准。avatar链接可能有防盗链限制直接使用需注意 Referer。常见错误排查HTTP 状态码层面状态码含义原因与处理200成功检查code是否为 0400参数错误url缺失或格式错误。确认是否传入了正确的抖音主页链接401鉴权失败X-API-Key无效或未传递。检查密钥是否正确、是否过期429请求频率过高超出 QPS 限制5/s。加入退避逻辑或降低并发500服务端错误临时故障可稍后重试。建议实现指数退避业务返回码codecode: 0→ 成功。code: -1或非 0 → 根据msg排查常见原因“参数错误”url非抖音用户主页。“用户不存在”该链接对应用户已注销或不公开。“请求过于频繁”同 429但业务层也会提示。若msg为“系统异常”可联系技术支持。工程化封装思路从简单的 curl 到生产级代码需要将请求逻辑封装成可复用、健壮的工具。以下以 Python 为例展示关键环节1. 基础函数import requests def fetch_douyin_user_info(url: str, api_key: str) - dict: 获取抖音用户公开信息。 :param url: 用户主页链接短链或长链 :param api_key: API Key :return: 解析后的 data 字典若失败返回 None headers {X-API-Key: api_key} params {url: url} try: resp requests.get( https://v1.apizero.cn/api/douyin-user, headersheaders, paramsparams, timeout10 ) resp.raise_for_status() # 触发 HTTP 错误 data resp.json() if data.get(code) ! 0: print(f业务错误: {data.get(msg)}) return None return data[data] except requests.exceptions.RequestException as e: print(f请求失败: {e}) return None2. 增强重试与退避import time from functools import wraps def retry(max_retries3, delay1): def decorator(func): wraps(func) def wrapper(*args, **kwargs): for attempt in range(max_retries): result func(*args, **kwargs) if result is not None: return result time.sleep(delay * (2 ** attempt)) # 指数退避 return None return wrapper return decorator retry(max_retries3, delay2) def fetch_douyin_user_info_with_retry(url: str, api_key: str) - dict: return fetch_douyin_user_info(url, api_key)3. 环境变量管理密钥import os api_key os.environ.get(APIZERO_API_KEY) if not api_key: raise ValueError(请设置环境变量 APIZERO_API_KEY)4. 批量调用与控制频率import time def batch_fetch(urls: list[str], api_key: str) - list[dict]: results [] for url in urls: info fetch_douyin_user_info_with_retry(url, api_key) results.append(info) time.sleep(0.2) # 控制 QPS ≤ 5留有余量 return results5. 日志与监控使用 Python 标准库logging记录每次请求的 status_code 和耗时便于排障import logging logger logging.getLogger(__name__) def fetch_with_logging(url, api_key): start time.time() info fetch_douyin_user_info(url, api_key) elapsed time.time() - start logger.info(fFetch {url} in {elapsed:.2f}s, result{ok if info else fail}) return info6. 注意事项URL 编码构建params字典时requests会自动编码无需手动处理。响应数据缓存对不频繁变化的数据如签名、昵称可缓存 5~10 分钟以减少请求量。异常全面捕获网络超时、JSON 解析失败、业务 code 非零等均需处理。API Key 安全禁止硬编码在代码仓库中应使用环境变量或密钥管理服务。合规使用请勿用于骚扰用户、爬取非公开数据或违反平台规则。参考文档官方文档页抖音用户公开信息 API 文档原始 Markdown 文档https://apizero.cn/aidocs/douyin-user/raw.md