Douyin Video Search
Douyin Video Search 将非空文本查询转换为范围明确的公开视频数据集。每个任务仅向服务商发起一次请求，固定使用第 1 页和 offset 0，再将返回记录按 SocQ reel-video 结构存储，便于后续统一读取。
主要特性
- 单字段请求契约公开请求只接受 query，无需服务商 token 或内部资源 ID；results_limit 等未声明字段会被拒绝。
- 范围固定的来源请求后端固定请求第 1 页和 offset 0，不向调用方开放服务商分页参数。
- 统一短视频记录以一致结构读取可用的正文、作者、媒体、时长、发布时间、采集时间，以及播放、点赞、评论与分享数量。
- 异步任务与存储结果提交后轮询任务；只有已完成任务存储的记录超出一次响应容量时，才使用 SocQ 结果游标继续读取。
参数
| 参数 | 必填 | 描述 |
|---|---|---|
query | 必填 | 必填的非空文本查询。后端会把它映射为服务商的 keyword 字段，而 page 与 offset 由后端固定。 |
如何使用
提交非空查询，等待异步任务完成，再读取该任务保存的标准化记录。
- 准备一个能明确描述目标公开视频的文本查询。
- 向 /v1/douyin/video-search POST query，并保存返回的 task_id。
- 轮询 /v1/tasks/{task_id}，直到任务成功或返回失败。
- 读取 data.results.items；has_more 为 true 时，把 next_cursor 用于任务结果请求，继续读取 SocQ 已存储记录。
curl -X POST "https://api.socq.ai/v1/douyin/video-search" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"street food"}'
# 轮询 GET /v1/tasks/{task_id}
# 读取 data.results.items；next_cursor 只分页读取 SocQ 存储结果最佳使用场景
- 主题视频发现： 围绕一个产品、话题、事件或研究短语建立范围明确的公开视频快照。
- 创作者语境补全： 把返回的文案与媒体和可用公开作者字段关联，用于定性研究与数据补全。
- 内容与媒体形式分析： 结合来源记录和查询语境，查看可用的视频媒体、缩略图、尺寸与时长。
- 可见互动快照： 比较可用的播放、点赞、评论和分享数量，并以 collected_at 标记观察时间。
使用建议
- 在自有界面中先去除首尾空白并确认 query 有实际内容，再提交任务。
- 不要提交 results_limit、page、offset、search_id 或服务商 cursor；这些都不属于 SocQ 公开请求结构。
- 将返回集合视为一次服务商响应，而不是完整搜索索引或可由调用方控制的排名窗口。
- 仅在任务提交后使用 GET /v1/tasks/{task_id} 的 cursor 与 limit 读取存储结果；limit 默认 50，范围为 1 至 500。
- 保留 collected_at，并允许作者、媒体、发布时间、时长及单项指标缺失，不要把空值替换为零。
相关 API
需要其他类型的 Douyin 公开数据时，可以使用以下 API。
- Douyin Live Room Detail API — 通过数字直播间 ID 获取一个已知抖音直播间，返回标准化直播间信息、主播身份、媒体和可见受众计数。
- Douyin User Profile API
- Douyin User Videos API
- Douyin Video Comments API
- Douyin Video Detail API