适用场景

在开发自动化工具或数据分析系统时，经常需要获取抖音用户的公开基础数据。以下三种场景尤其典型：

1. 账号健康度监控：运营团队可以定时拉取自有账号的粉丝数、获赞数，判断内容趋势是否正常，及时发现异常掉粉。
2. 竞品或KOL分析：通过批量采集多个抖音大V的粉丝数和作品数，建立行业基准，辅助决策投放策略。
3. 后台数据展示：在自有管理面板中集成用户信息卡片，无需手动访问抖音主页，提升内部效率。

接口能力边界

本接口专门用于获取抖音用户主页的公开信息，支持的输入包括：

• 抖音短链：https://v.douyin.com/xxxxx/（自动展开）
• 长链：https://www.douyin.com/user/MS4wLjABAAAA...

返回的字段均为用户在平台上公开展示的内容，包括：

字段	说明
nickname	用户昵称
avatar	头像URL
signature	个人签名
aweme_count	作品总数
follower_count	粉丝数
following_count	关注数
total_favorited	获赞总数
uid	用户唯一标识

注意：接口仅返回公开信息，不会涉及私密数据（如手机号、私信记录等）。QPS限制为5次/秒，超出后会返回429状态码。

请求参数与鉴权

请求方式

• 方法：GET
• 地址：https://v1.apizero.cn/api/douyin-user
• Query参数：
  • url（必填，string）：抖音用户主页的完整链接。支持短链或长链。若链接中包含中文字符或特殊符号，需进行URL编码。

鉴权方式

在HTTP请求头中添加：

X-API-Key: <你的API密钥>

密钥需提前从平台获取并妥善保管。未提供有效密钥将返回401错误。

curl 示例

以下是一个可直接复制的curl命令，替换YOUR_API_KEY和<用户主页链接>即可使用：

curl -sS \
  -X GET \
  -H "X-API-Key: YOUR_API_KEY" \
  "https://v1.apizero.cn/api/douyin-user?url=https://www.douyin.com/user/MS4wLjABAAAA..."

如果使用短链，例如https://v.douyin.com/xxxxx/，直接填入url参数即可，接口会自动展开。

代码接入（Python）

使用Python的requests库可以方便地调用。以下是带错误处理的完整示例：

import requests
import sys

API_KEY = "your_api_key_here"
BASE_URL = "https://v1.apizero.cn/api/douyin-user"

def get_douyin_user_info(user_url):
    """
    获取抖音用户公开信息
    :param user_url: 用户主页链接
    :return: dict 或 None
    """
    headers = {"X-API-Key": API_KEY}
    params = {"url": user_url}
    
    try:
        resp = requests.get(BASE_URL, params=params, headers=headers, timeout=10)
        resp.raise_for_status()
        data = resp.json()
        
        if data.get("code") == 0:
            return data["data"]
        else:
            print(f"API返回错误: {data.get('msg')}", file=sys.stderr)
            return None
    except requests.exceptions.RequestException as e:
        print(f"网络请求失败: {e}", file=sys.stderr)
        return None

# 使用示例
if __name__ == "__main__":
    test_url = "https://www.douyin.com/user/MS4wLjABAAAA..."
    result = get_douyin_user_info(test_url)
    if result:
        print(f"昵称: {result.get('nickname')}")
        print(f"粉丝数: {result.get('follower_count')}")
        print(f"获赞数: {result.get('total_favorited')}")

进阶：批量请求与并发控制

若需同时查询多个用户，建议使用asyncio与aiohttp异步库，或利用concurrent.futures.ThreadPoolExecutor控制并发数不超过5（QPS限制）。下面给出一个简单线程池版本：

from concurrent.futures import ThreadPoolExecutor, as_completed

def batch_query(urls, max_workers=3):
    with ThreadPoolExecutor(max_workers=max_workers) as executor:
        fut_to_url = {executor.submit(get_douyin_user_info, url): url for url in urls}
        for fut in as_completed(fut_to_url):
            url = fut_to_url[fut]
            try:
                info = fut.result()
                if info:
                    print(f"{url} -> 昵称: {info['nickname']}")
            except Exception as e:
                print(f"{url} 失败: {e}")

返回值解读

成功时的响应结构：

{
  "code": 0,
  "data": {
    "nickname": "张三",
    "avatar": "https://p3-xxx.byteimg.com/xxx",
    "signature": "分享美好生活",
    "aweme_count": 123,
    "follower_count": 9999,
    "following_count": 200,
    "total_favorited": 100000,
    "uid": "MS4wLjABAAAA..."
  },
  "msg": "成功"
}

字段说明：

• code：整型，0表示成功，非0为错误码。
• msg：字符串，状态描述。
• data：对象，包含用户公开数据：
  • nickname：用户昵称（可能为空字符串）。
  • avatar：头像CDN链接。
  • signature：个人简介，若未设置则为空。
  • aweme_count：已发布作品数。
  • follower_count：粉丝总数。
  • following_count：关注数。
  • total_favorited：累计获赞数。
  • uid：抖音内部用户ID，可用于其他关联接口。

失败时的响应（示例）：

{
  "code": 400,
  "msg": "参数url缺失或格式错误"
}

常见错误与排查

状态码	返回code	可能原因	处理方式
401	1001	API Key无效或未提供	检查X-API-Key头部是否正确
400	400	url参数缺失、为空或格式错误	确认链接是抖音用户主页，并进行URL编码
404	1004	用户不存在或链接解析失败	核对链接是否有效（用户可能已注销）
429	1029	请求频率超过QPS限制（5/s）	加入重试机制，使用指数退避
500	1500	服务器内部错误	稍后重试，若持续则反馈文档支持

当遇到429时，推荐的重试策略：

import time
import random

def retry_request(url, max_retries=3):
    for i in range(max_retries):
        result = get_douyin_user_info(url)
        if result:
            return result
        time.sleep((2 ** i) + random.uniform(0, 1))
    return None

工程化注意事项

1. 缓存设计：对于短时间内重复查询同一用户（如监控脚本每10分钟跑一次），应缓存数据5–10分钟，减少API调用。可使用cachetools或Redis。
2. URL处理：用户提供的链接可能包含多余的空格或UTF-8字符，务必在请求前做urllib.parse.quote（仅对路径部分编码，保留协议和域名）。
3. 异步与限流：建议在异步框架中使用asyncio.Semaphore(5)或aiohttp.TCPConnector(limit=5)，确保瞬时并发不超过5。
4. 日志记录：为每个请求记录url、耗时、返回码，方便排查问题。可结合structlog输出结构化日志。
5. 监控告警：若连续多次请求失败或延迟异常，应触发告警通知。

参考文档

• API文档页
• 原始文档（Markdown）