抖音用户公开信息API：一个最小可运行的curl示例
适用场景
抖音用户公开信息 API 适用于以下场景：
- 数据分析：获取用户主页的公开指标（粉丝数、获赞数、作品数），用于内容运营或竞品分析。
- 内容监控：定期拉取指定用户的公开数据，监控其账号增长趋势。
- 工具集成：在自有后台或应用中展示目标用户的概览信息（如昵称、头像）。
该 API 仅需一个用户主页链接（支持短链v.douyin.com或长链douyin.com/user/），即可一次性获取多个维度数据，无需模拟浏览器或处理 Cookie，大大降低了接入维护复杂度。
接口能力边界
- 请求方式：GET
- 请求地址：
https://v1.apizero.cn/api/douyin-user - 返回格式：JSON
- QPS 限制：5 次/秒（超出会返回限流错误）
- 数据范围：仅返回用户在抖音上公开显示的信息，不包含私密数据（如私信数、主页浏览量）。
- 自动展开短链：如果传入
v.douyin.com短链，接口会自动重定向解析，返回最终用户的数据。
注意：该接口一次请求只能获取一个用户的信息，不支持批量查询。如需批量查询，需在业务层循环调用并控制频率。
参数与鉴权
Query 参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
url | string | 是 | 抖音用户主页链接。支持格式：https://v.douyin.com/xxxx/或https://www.douyin.com/user/MS4wLjAB... |
鉴权方式
在请求 Header 中携带X-API-Key字段，值为你的 API Key。
示例 Header：
X-API-Key: your_api_key_hereAPI Key 需要在 API 平台申请获取，每个 Key 有独立的 QPS 和调用配额。
完整请求模板
curl -sS \ -X GET \ -H "X-API-Key: $APIZERO_API_KEY" \ "https://v1.apizero.cn/api/douyin-user?url=<url>"最小可运行示例
以下示例使用curl调用接口。请将YOUR_API_KEY替换为你的真实 API Key，并将<用户主页链接>替换为目标用户的完整主页链接（示例中用YOUR_TARGET_URL表示）。
# 设置环境变量（或直接替换） export API_KEY="YOUR_API_KEY" curl -sS \ -X GET \ -H "X-API-Key: $API_KEY" \ "https://v1.apizero.cn/api/douyin-user?url=YOUR_TARGET_URL" | jq .提示：使用
jq工具可以格式化 JSON 输出。如果没有安装，可去掉| jq .。
示例输出（成功）：
{ "code": 0, "data": { "aweme_count": 123, "follower_count": 9999, "nickname": "张三", "total_favorited": 100000 }, "msg": "成功" }示例输出（失败 — URL 无效）：
{ "code": -1, "msg": "url 不合法，请检查后重试", "data": null }返回值解读
接口返回的 JSON 顶层包含三个字段：
| 字段 | 类型 | 说明 |
|---|---|---|
code | int | 状态码：0表示成功，其他值表示失败 |
msg | string | 状态描述信息 |
data | object/null | 用户数据对象，失败时为null |
data 对象字段
| 字段 | 类型 | 说明 |
|---|---|---|
nickname | string | 用户昵称 |
avatar | string | 用户头像 URL（可能为空） |
signature | string | 用户简介/签名（可能为空） |
aweme_count | int | 作品发布总数 |
follower_count | int | 粉丝数量 |
following_count | int | 关注数量 |
total_favorited | int | 获赞总数 |
注意：实际返回字段以接口文档为准，上述字段为常见字段示例。接口可能返回更多字段（如
cover_thumb、user_id等），建议在调用时对未知字段做宽容处理。
常见错误排查
1.code: -1且msg: "url 不合法"
- 原因：传入的
url参数不是有效的抖音用户主页链接。 - 解决：检查链接是否为
v.douyin.com或douyin.com/user/开头，并注意链接是否被截断。可以尝试直接复制浏览器地址栏的链接。
2.code: -1且msg: "API Key 无效"
- 原因：
X-API-KeyHeader 未传递或 Key 不正确。 - 解决：确认 Key 是否正确，且没有在请求中漏传 Header。建议使用环境变量管理 Key，避免硬编码。
3. HTTP 429 Too Many Requests
- 原因：QPS 超过 5 次/秒。
- 解决：在代码中加入重试或延时逻辑，确保每秒请求不超过 5 次。严禁在无限制的 for 循环中连续调用。
4.code为其他负值或data为 null
- 原因：可能是接口内部错误或用户不存在。
- 解决：检查
msg字段的描述，若持续出现请联系接口技术支持。
工程化注意事项
API Key 安全：切勿将 API Key 硬编码在客户端代码或公开仓库中。建议通过环境变量或密钥管理服务注入。
QPS 控制：如果你的业务需要批量查询（例如每天扫描上千个用户），必须实现流量控制。推荐使用令牌桶算法或简单的时间间隔队列。
URL 编码：
url参数在 curl 中可以直接传入完整链接，但如果在 GET 请求中拼接时，建议对 URL 进行 URL 编码（尤其当链接包含特殊字符时）。# 使用 curl 的 --data-urlencode 或手动编码 URL_ENCODED=$(python3 -c "import urllib.parse; print(urllib.parse.quote('https://v.douyin.com/xxxx/', safe=''))") curl -X GET "https://v1.apizero.cn/api/douyin-user?url=$URL_ENCODED" -H "X-API-Key: $API_KEY"错误重试：对于网络抖动或限流返回的 HTTP 429，建议采用指数退避重试策略（如第一次等待 1 秒后重试，第二次 2 秒，最多 3 次）。
数据缓存：用户公开信息的更新频率通常较低（几小时到一天），如果不需要实时数据，可以在本地缓存 1~6 小时，减少 API 调用次数。
响应字段兼容：接口未来可能新增字段，代码中访问字段时应做安全检查（如
data.follower_count可能不存在），或使用防御性解析。环境隔离：开发环境使用测试 Key，生产环境使用正式 Key，并配置不同的 QPS 策略。
参考文档
- 接口文档页面：https://apizero.cn/aidocs/douyin-user
- 原始 Markdown 文档：https://apizero.cn/aidocs/douyin-user/raw.md
- API 平台主页：以实际文档为准，本文不提供链接。