主题
YouTube 视频字幕实时获取（高级版）
POST /v3/serp/youtube/video_subtitles/live/advanced
接口概述
/v3/serp/youtube/video_subtitles/live/advanced 用于实时获取指定 YouTube 视频的字幕。 本接口会返回该视频观看页中的字幕文本，以及对应的字幕语言、起止时间和持续时长。
- 请求方式：
POST - 接口地址：
https://api.seermartech.cn/v3/serp/youtube/video_subtitles/live/advanced - 返回格式：
JSON - 任务模式：实时（Live）
- 单次请求支持 1 个任务
- 频率限制：最高 2000 次 API 调用/分钟
计费说明
该接口按请求计费。 参考价约 ¥0.0960 / 次
扣费以响应头 X-SeerMarTech-Charge-CNY 为准。
请求格式
所有 POST 数据使用 UTF-8 编码的 JSON 格式提交，请求体需为 JSON 数组：
json
[
{
"language_code": "en",
"location_code": 2840,
"video_id": "Y8Wu4rSNJms"
}
]主参数
| 字段名 | 类型 | 说明 |
|---|---|---|
video_id | string | 视频 ID，填。可从视频 URL 中获取，也可从 /v3/serp/youtube/organic/live/advanced 的 youtube_video 结果项中获取。示例：Y8Wu4rSNJms |
location_code | integer | 搜索引擎地域代码。当未指定 location_name 时填；指定后可不传 location_name。可通过 /v3/serp/youtube/locations 获取可用地域列表。示例：2840 |
language_code | string | 搜索引擎语言代码。当未指定 language_name 时填；指定后可不传 language_name。可通过 /v3/serp/youtube/languages 获取可用语言列表。示例：en |
device | string | 设备类型，可选。支持：desktop |
附加参数
| 字段名 | 类型 | 说明 |
|---|---|---|
location_name | string | 搜索引擎地域名。当未指定 location_code 时填；指定后可不传 location_code。可通过 /v3/serp/youtube/locations 获取。示例：United States |
language_name | string | 搜索引擎语言名。当未指定 language_code 时填；指定后可不传 language_code。可通过 /v3/serp/youtube/languages 获取。示例：English |
os | string | 设备操作系统，可选。可选值：windows、macos。默认值：windows |
tag | string | 自定义任务标识，可选，最长 255 个字符。可用于请求与响应结果的对应，返回时会出现在响应的 data 对象中 |
subtitles_language | string | 原始字幕语言代码。可从 YouTube 视频信息接口结果中获取 |
subtitles_translate_language | string | 目标翻译语言代码。支持大量语言代码，详见下方列表 |
subtitles_translate_language 可选值
"az", "ay", "ak", "sq", "am", "en", "ar", "hy", "as", "af", "eu", "be", "bn", "my", "bg", "bs", "bho", "cy", "hu", "vi", "haw", "ht", "gl", "lg", "el", "ka", "gn", "gu", "gd", "da", "fy", "zu", "iw", "ig", "yi", "id", "ga", "is", "es", "it", "yo", "kk", "kn", "ca", "qu", "rw", "ky", "zh-Hant", "zh-Hans", "ko", "co", "xh", "ku", "km", "lo", "la", "lv", "ln", "lt", "lb", "mk", "mg", "ms", "ml", "dv", "mt", "mi", "mr", "mn", "und", "de", "ne", "nl", "no", "ny", "or", "om", "pa", "fa", "pl", "pt", "ps", "ro", "ru", "sm", "sa", "ceb", "nso", "sr", "si", "sd", "sk", "sl", "so", "sw", "su", "tg", "th", "ta", "tt", "te", "ti", "ts", "tr", "tk", "uz", "ug", "uk", "ur", "fil", "fi", "fr", "ha", "hi", "hmn", "hr", "cs", "sv", "sn", "ee", "eo", "et", "st", "jv", "ja", "kri"
响应结构
接口返回 JSON 数据，顶层 tasks 数组，用于描述本次提交的任务及执行结果。
顶层字段
| 字段名 | 类型 | 说明 |
|---|---|---|
version | string | 当前 API 版本 |
status_code | integer | 通用状态码，完整列表参考 /v3/appendix/errors |
status_message | string | 通用提示信息，完整列表参考 /v3/appendix/errors |
time | string | 执行耗时，单位秒 |
cost | float | 本次请求总费用，单位 USD |
tasks_count | integer | tasks 数组中的任务数 |
tasks_error | integer | 返回错误的任务数 |
tasks | array | 任务数组 |
tasks 数组字段
| 字段名 | 类型 | 说明 |
|---|---|---|
id | string | 任务唯一标识，UUID 格式 |
status_code | integer | 任务状态码，范围通常为 10000-60000，完整列表参考 /v3/appendix/errors |
status_message | string | 任务提示信息 |
time | string | 任务执行耗时，单位秒 |
cost | float | 当前任务费用，单位 USD |
result_count | integer | result 数组中的数量 |
path | array | URL 路径 |
data | object | 你在 POST 请求中提交的参数副本 |
result | array | 结果数组 |
result 数组字段
| 字段名 | 类型 | 说明 |
|---|---|---|
video_id | string | 请求中的视频 ID |
se_domain | string | 请求对应的搜索引擎域名 |
location_code | integer | 请求中的地域代码 |
language_code | string | 请求中的语言代码 |
check_url | string | 对应结果页的直达链接，可用于人工校验结果准确性 |
datetime | string | 结果抓取时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00 |
spell | object | 搜索引擎自动纠错信息；若发生纠错，将返回纠正后的查询及类型 |
refinement_chips | object | 搜索细分标签，固定为 null |
item_types | array | SERP 中返回的结果类型列表；本接口可能值为 youtube_subtitles |
unsupported_language | boolean | 指示当前语言是否不被系统支持 |
translate_language | string | 翻译后的字幕语言代码 |
origin_language | string | 原始字幕语言代码 |
category | string | 视频所属分类。该字段已废弃，始终返回 null |
subtitles_count | integer | 视频字幕条数 |
title | string | 视频标题 |
items_count | integer | items 数组中的结果数量 |
items | array | 字幕结果列表 |
items 数组字段
| 字段名 | 类型 | 说明 |
|---|---|---|
type | string | 结果类型，固定为 youtube_subtitles |
rank_group | integer | 同类型结果组排名 |
rank_absolute | integer | 在结果中的绝对排名 |
text | string | 字幕文本；当设置翻译语言时，此处通常为翻译后的文本 |
start_time | integer / float | 该字幕开始出现的时间点（秒） |
end_time | integer / float | 该字幕结束时间点（秒） |
duration_time | integer / float | 该字幕持续时长（秒） |
请求示例
cURL
bash
curl --location --request POST "https://api.seermartech.cn/v3/serp/youtube/video_subtitles/live/advanced" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
{
"language_code": "en",
"location_code": 2840,
"video_id": "Y8Wu4rSNJms",
"subtitles_language": "en",
"subtitles_translate_language": "it",
"device": "desktop",
"os": "windows"
}
]'Python
python
import requests
url = "https://api.seermartech.cn/v3/serp/youtube/video_subtitles/live/advanced"
headers = {
"Authorization": "Bearer smt_live_YOUR_KEY",
"Content-Type": "application/json"
}
data = [
{
"language_code": "en",
"location_code": 2840,
"video_id": "Y8Wu4rSNJms",
"subtitles_language": "en",
"subtitles_translate_language": "it",
"device": "desktop",
"os": "windows"
}
]
response = requests.post(url, headers=headers, json=data)
result = response.json
if result.get("status_code") == 20000:
print(result)
else:
print(f'error. Code: {result.get("status_code")} Message: {result.get("status_message")}')TypeScript
typescript
import axios from "axios";
async function getYoutubeSubtitles {
const response = await axios.post(
"https://api.seermartech.cn/v3/serp/youtube/video_subtitles/live/advanced",
[
{
language_code: "en",
location_code: 2840,
video_id: "Y8Wu4rSNJms",
subtitles_language: "en",
subtitles_translate_language: "it",
device: "desktop",
os: "windows",
},
],
{
headers: {
Authorization: "Bearer smt_live_YOUR_KEY",
"Content-Type": "application/json",
},
}
);
const result = response.data;
if (result.status_code === 20000) {
console.log(result);
} else {
console.log(`error. Code: ${result.status_code} Message: ${result.status_message}`);
}
}
getYoutubeSubtitles;响应示例
json
{
"version": "0.1.20220819",
"status_code": 20000,
"status_message": "Ok.",
"time": "2.4625 sec.",
"cost": 0.006,
"tasks_count": 1,
"tasks_error": 0,
"tasks": [
{
"data": {
"api": "serp",
"function": "live",
"se": "youtube",
"se_type": "video_subtitles",
"language_code": "en",
"location_code": 2840,
"video_id": "Y8Wu4rSNJms",
"subtitles_language": "en",
"subtitles_translate_language": "it",
"device": "desktop",
"os": "windows"
},
"result": [
{
"unsupported_language": false,
"translate_language": "it",
"origin_language": "en",
"category": null,
"subtitles_count": 31,
"title": "How to set up BMW eDrive Modes in the New Generation of BMW Plug-In Hybrids",
"items_count": 31,
"items": [
{
"type": "youtube_subtitles",
"rank_group": 30,
"rank_absolute": 30,
"text": "...",
"start_time": 69.33,
"end_time": 75.12,
"duration_time": 5.789
},
{
"type": "youtube_subtitles",
"rank_group": 31,
"rank_absolute": 31,
"text": "",
"start_time": 73.04,
"end_time": 75.12,
"duration_time": 2.079
}
]
}
]
}
]
}状态码与错误处理
- 顶层
status_code表示整次请求的执行状态 tasks[].status_code表示单个任务的执行状态- 建议同时校验：
- HTTP 状态码
- 顶层
status_code - 任务级
tasks[].status_code - 错误码与通用提示信息请参考：
/v3/appendix/errors
由于实时接口直接返回结果，建议在业务侧做好以下处理：
- 请求参数校验，如
video_id、语言和地域参数是否齐 - 状态码异常重试或降级
- 对
unsupported_language=true的场景进行容处理 - 对空字幕文本或字幕条数为 0 的结果进行底判断
使用说明
- 每次 Live 请求能提交一个任务
location_code与location_name二选一language_code与language_name二选一- 若需要翻译字幕，请传
subtitles_translate_language - 若需要指定字幕原文语言，可传
subtitles_language - 本接口适合提取视频字幕文本、构建多语言分析流程，以及结合时间轴做分段处理
实用场景
- 提取视频字幕正文：抓取指定视频的完整字幕文本，用于 SEO整理、视频转文章和知识库沉淀。
- 翻译多语言字幕：将原始字幕实时转换为目标语言，支持海外监测、本地化运营与跨语种选题分析。
- 定位片段：基于
start_time、end_time和duration_time精确识别视频中某段字幕出现的时间，便于剪辑、摘要和重点标注。 - 分析竞品视频表达：抓取竞品频道视频字幕，研究结构、表达与主题覆盖策略。
- 构建视频语料库：批量沉淀字幕数据，为品牌词监测、主题聚类、问答挖掘和训练分析模型提供基础数据。