TikTok Video Transcript API

TikTok Video Transcript

主要特性

• 多 URL 字幕查询在一个任务中处理一个或多个 TikTok 公开视频 URL，并可为每次查询传入语言偏好。
• 标准化文本与来源信息以一致结构返回字幕文本、语言、纯文本或 WebVTT 格式、来源 URL、记录 ID、shortcode 和采集时间。
• 仅保留可用字幕只有来源返回非空字幕文本时才生成结果，因此响应不会用占位记录代替不可用字幕。

参数

如何使用

把已知的 TikTok 公开视频 URL 作为异步任务提交，轮询 task ID，再将标准化字幕记录与请求来源逐一核对。

1. 准备一个或多个可访问的 TikTok 公开视频 URL；需要指定语言时，使用 en 等两字母语言代码。
2. 把 urls 和可选的 language POST 到 /v1/tiktok/video-transcript，并保存返回的 task_id。
3. 轮询 /v1/tasks/{task_id}，直到状态为 succeeded 或 failed；任务成功时，结果数仍可能少于输入 URL 数。
4. 读取 data.results.items，按 url 与输入列表核对；results.has_more 为 true 时继续传入 results.next_cursor。

curl -X POST "https://api.socq.ai/v1/tiktok/video-transcript" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://www.tiktok.com/@stoolpresidente/video/7499229683859426602"],"language":"en"}'

# 轮询 GET /v1/tasks/{task_id}
# 读取 data.results.items，并在 has_more 为 true 时继续传入 next_cursor

最佳使用场景

• 可检索语音内容归档： 将字幕文本与来源 URL、语言、格式、shortcode 和采集时间一同索引，按口播词检索选定的公开视频。
• 关键词与主题分析： 分析已知视频集合中的标准化文本，查找重复出现的词语、短语与主题，同时保留来源链接便于复核。
• 无障碍与引文审核： 利用可用字幕文本和格式信息整理易读文本或查找相关段落，再回到关联的公开视频核对内容。

使用建议

• 提交前确认每个地址都能打开目标 TikTok 公开视频，因为请求只检查 URL 字符串非空，不会强制校验 TikTok 主机名或 /video/{id} 路径。
• 批量提交前统一 URL 并移除跟踪参数等变体，因为系统去除首尾空白后只会合并完全相同的字符串。
• 指定语言时使用 en 等两字母代码，并依据结果中的 language 安排后续处理，不要假定语言偏好一定得到满足。
• 任务成功后将返回的 url 与输入列表对比，保留没有结果的公开视频、私密视频、已删除视频、受限视频以及无可用字幕或语音的视频。
• 根据 format 选择解析方式，WebVTT 存在时保留提示结构；created_at 不含视频发布时间，数据追溯应使用 collected_at。

相关 API