Kwai User Posts
Kwai 用户帖子是公开账号发布的内容，可包含文案、作者身份、关联媒体、话题、提及、发布时间和可见互动数量。结合内容字段与采集时间，可用于账号内容研究、媒体形式梳理和特定时间点的互动表现比较。
主要特性
- 两种账号定位方式可提交用户名，也可提交 kwai.com 或 kwai-video.com 上的公开主页 URL；请求至少需要其中一种。
- 采集一个来源页每个任务获取服务商为指定公开账号返回的一页帖子，不向调用方开放来源游标或来源结果数量参数。
- 统一内容与作者结构以一致的帖子结构返回正文、公开作者字段、来源 URL、媒体、话题、提及、发布时间与采集时间。
- 可见互动快照保留可用的点赞、评论、分享和观看数量，并通过 collected_at 标明每次观察的时间。
参数
| 参数 | 必填 | 描述 |
|---|---|---|
url | 必填（至少一项） | 非空 Kwai 主页地址，解析后的 hostname 必须为 kwai.com、kwai-video.com 或两者的子域名；包含 authority 和 hostname 时可使用任意 scheme，也接受协议相对地址。url 与 username 至少提交一个，也可以同时提交。 |
username | 必填（至少一项） | Kwai 用户名，可带一个前导 @，随后使用 1 至 64 个 ASCII 字母、数字、点、下划线或连字符，总长度最多为 65 个字符；该值会作为 handle 传给服务商。 |
如何使用
提交受支持的 Kwai 账号标识，等待异步任务完成，再分页读取已存储的标准化结果。
- 准备一个 Kwai 用户名，或 kwai.com、kwai-video.com 上的公开主页 URL。
- 向 /v1/kwai/user-posts POST url 或 username，并保存返回的 task_id。
- 轮询 /v1/tasks/{task_id}，直到任务成功或返回失败。
- 读取 data.results.items；has_more 为 true 时继续使用任务结果的 next_cursor。该游标只分页读取存储结果，不会翻取 Kwai 来源页。
curl -X POST "https://api.socq.ai/v1/kwai/user-posts" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://www.kwai.com/@ShortShortz8"}'
# 轮询 GET /v1/tasks/{task_id}
# 读取 data.results.items；has_more 为 true 时沿存储结果的 next_cursor 继续最佳使用场景
- 公开账号内容研究： 查看指定账号的文案、作者归属、公开媒体、话题、提及和发布时间。
- 媒体形式梳理： 按可用的媒体类型、时长、缩略图和尺寸整理帖子，同时保留原始帖子与作者关联。
- 特定时间点互动比较： 比较帖子的可见点赞、评论、分享和观看数量，并以 collected_at 区分每次采集观察。
使用建议
- 提交前将用户名整理为允许的可选 @ 格式，并校验主页 URL 是否属于 kwai.com 或 kwai-video.com。
- 不要向来源请求添加 cursor 或 results_limit：每个任务只用受支持的账号字段向服务商请求一页。
- 任务提交后，如需分页读取存储结果，再使用 GET /v1/tasks/{task_id} 的 cursor 与 limit；limit 默认 50，范围为 1 至 500。
- 正文、作者详情、各项互动指标、媒体、话题、提及和发布时间都可能缺失；请用 collected_at 标记快照时间。
相关 API
需要其他类型的 Kwai 公开数据时，可以使用以下 API。
- Kwai Profile API — 通过 username 或受支持 URL 获取一个公开 Kwai 主页，返回标准化身份、图片、账号标记、可见计数和采集上下文。
- Kwai Post API — 将一个已知的公开 Kwai 帖子 URL 解析为标准化内容、作者、媒体、时间、实体和可见互动字段。