接口速览

在开发创作者工具、数据看板或账号运营脚本时，经常需要读取某个抖音用户主页上的公开数据，比如昵称、粉丝数、作品数、获赞总数等。抖音用户公开信息 API 正是为此设计：只要给一个用户主页链接，无论是v.douyin.com开头的短链，还是douyin.com/user/开头的长链，接口都会自动识别并返回结构化 JSON 数据。

本文不展开平台层面的介绍，只聚焦于一个最小的可运行示例，带你走通从拼装请求到解析返回结果的完整链路。

适用场景

这个接口适合以下几类轻量级需求：

• 定时拉取自己或授权账号的粉丝量、作品量，用于简单趋势记录。
• 在后台管理系统中展示抖音账号的基础资料卡片。
• 对一批主页链接做批量校验，判断链接是否有效、账号是否存在。
• 为数据报表提供“作品数 / 粉丝数 / 获赞总数”等指标。

因为接口只返回公开信息，不涉及私密数据，所以适用于合规的数据采集场景。

接口能力边界

在调用之前，先明确以下边界：

• 输入：抖音用户主页链接，支持短链和长链。
• 输出：昵称、头像、签名等公开字段，以及作品数、粉丝数、关注数、获赞总数。
• QPS：5 次/秒，超出后需要等待或使用限速逻辑。
• 短链处理：接口会自动展开v.douyin.com短链，不需要客户端自行跟随重定向。

根据官方文档的响应示例，data中至少包含aweme_count、follower_count、nickname、total_favorited这些字段。其他字段是否返回、返回格式如何，以实际请求结果和文档为准。

鉴权方式

接口采用 Header 鉴权，需要在请求头中携带X-API-Key。

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

建议不要把 Key 直接写死在命令里，而是通过环境变量传入。例如在 Linux / macOS 上先导出变量：

export APIZERO_API_KEY="your-key-here"

这样后续的 curl 示例可以直接引用$APIZERO_API_KEY，避免密钥泄露。

最小可运行示例：curl

方式一：将 url 直接作为 Query 参数

把抖音用户主页链接拼接到请求地址中。注意url参数必须存在，且需要做 URL 编码，否则链接中的特殊字符可能被解释器截断。

curl -sS \ -X GET \ -H "X-API-Key: $APIZERO_API_KEY" \ "https://v1.apizero.cn/api/douyin-user?url=https%3A%2F%2Fv.douyin.com%2Fxxxxx"

方式二：使用 --data-urlencode 自动编码

如果不想手写编码，可以借助 curl 的-G和--data-urlencode，让 curl 自动处理链接中的特殊字符：

curl -sS \ -G \ "https://v1.apizero.cn/api/douyin-user" \ -H "X-API-Key: $APIZERO_API_KEY" \ --data-urlencode "url=https://v.douyin.com/xxxxx"

两种写法等价，推荐使用第二种，尤其是当主页链接带有其他参数或转义字符时，更不容易出错。

返回字段解读

成功时，接口返回的 JSON 结构如下（来自文档响应示例节选）：

{ "code": 0, "data": { "aweme_count": 123, "follower_count": 9999, "nickname": "张三", "total_favorited": 100000 }, "msg": "成功" }

其中顶层字段含义：

data内部核心字段：

注意：文档的“响应示例节选”中展示的顶层是一个数组，里面包含status、description、example等字段。那是 OpenAPI 文档的响应定义。实际调用后，客户端收到的是example中的结构，即code/data/msg对象。

常见错误排查

如果请求没有返回预期结果，可以按照以下顺序排查：

1. HTTP 401 / 403：说明X-API-Key缺失或无效。检查环境变量是否设置、Key 是否复制正确。
2. HTTP 400：说明请求参数有误，最常见的是url参数不存在或没有正确编码。确认是否传了url，以及链接是否被完整送入。
3. 返回code非 0：说明业务逻辑上出了问题，比如链接无法解析为有效用户主页、用户不存在、链接不是抖音主页等。此时应结合msg的提示修改输入。
4. 空数据或字段缺失：确认用户主页是否真实存在，以及该账号是否有公开数据。
5. 请求超时：可能是网络问题或 API 服务暂时不可用，可以稍后重试，但不要高频重试。

工程化注意事项

把接口用到真实项目中时，除了直接 curl，还需要关注以下几点：

URL 编码

抖音短链中可能包含斜杠、问号、空格等字符。在代码中建议使用URLEncoder.encode(url, "UTF-8")或--data-urlencode进行编码，避免因为参数解析错误导致 400。

API Key 管理

不要在前端代码或公开仓库中暴露 Key。推荐的做法是放在后端环境变量或密钥管理服务中，由服务端发起请求。

限速与重试

QPS 限制为 5 次/秒。如果需要批量处理大量链接，建议在代码中加入简单的令牌桶或睡眠间隔。重试时使用指数退避，例如 1s、2s、4s，最多 3 次。

数据缓存

用户主页数据更新频率通常不高，尤其是作品数和粉丝数这类指标，没必要每次请求都实时拉取。建议在业务层加一层缓存，比如 5 分钟或 10 分钟失效，减少 API 调用量。

字段变化

接口返回的字段可能随版本调整。开发时不要硬编码所有字段，应该对data做空值保护，并预留未知字段的兼容处理。

参考文档

• 文档页：https://apizero.cn/aidocs/douyin-user
• 原始文档：https://apizero.cn/aidocs/douyin-user/raw.md