接口速览
在开发创作者工具、数据看板或账号运营脚本时，经常需要读取某个抖音用户主页上的公开数据，比如昵称、粉丝数、作品数、获赞总数等。抖音用户公开信息 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": "成功" }其中顶层字段含义：
| 字段 | 类型 | 说明 |
|---|---|---|
code | number | 业务状态码，0表示成功 |
msg | string | 描述信息 |
data | object | 用户公开数据对象 |
data内部核心字段：
| 字段 | 类型 | 示例 | 说明 |
|---|---|---|---|
nickname | string | 张三 | 用户昵称 |
follower_count | number | 9999 | 粉丝数 |
aweme_count | number | 123 | 作品数 |
total_favorited | number | 100000 | 获赞总数 |
注意：文档的“响应示例节选”中展示的顶层是一个数组，里面包含
status、description、example等字段。那是 OpenAPI 文档的响应定义。实际调用后，客户端收到的是example中的结构，即code/data/msg对象。
常见错误排查
如果请求没有返回预期结果，可以按照以下顺序排查：
- HTTP 401 / 403：说明
X-API-Key缺失或无效。检查环境变量是否设置、Key 是否复制正确。 - HTTP 400：说明请求参数有误，最常见的是
url参数不存在或没有正确编码。确认是否传了url，以及链接是否被完整送入。 - 返回
code非 0：说明业务逻辑上出了问题，比如链接无法解析为有效用户主页、用户不存在、链接不是抖音主页等。此时应结合msg的提示修改输入。 - 空数据或字段缺失：确认用户主页是否真实存在，以及该账号是否有公开数据。
- 请求超时：可能是网络问题或 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