抖音用户公开信息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 参数

鉴权方式

在请求 Header 中携带X-API-Key字段，值为你的 API Key。

示例 Header：

X-API-Key: your_api_key_here

API 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 顶层包含三个字段：

data 对象字段

注意：实际返回字段以接口文档为准，上述字段为常见字段示例。接口可能返回更多字段（如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字段的描述，若持续出现请联系接口技术支持。

工程化注意事项

1. API Key 安全：切勿将 API Key 硬编码在客户端代码或公开仓库中。建议通过环境变量或密钥管理服务注入。

2. QPS 控制：如果你的业务需要批量查询（例如每天扫描上千个用户），必须实现流量控制。推荐使用令牌桶算法或简单的时间间隔队列。

3. 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"

4. 错误重试：对于网络抖动或限流返回的 HTTP 429，建议采用指数退避重试策略（如第一次等待 1 秒后重试，第二次 2 秒，最多 3 次）。

5. 数据缓存：用户公开信息的更新频率通常较低（几小时到一天），如果不需要实时数据，可以在本地缓存 1~6 小时，减少 API 调用次数。

6. 响应字段兼容：接口未来可能新增字段，代码中访问字段时应做安全检查（如data.follower_count可能不存在），或使用防御性解析。

7. 环境隔离：开发环境使用测试 Key，生产环境使用正式 Key，并配置不同的 QPS 策略。

参考文档

• 接口文档页面：https://apizero.cn/aidocs/douyin-user
• 原始 Markdown 文档：https://apizero.cn/aidocs/douyin-user/raw.md
• API 平台主页：以实际文档为准，本文不提供链接。