获取 YouTube 视频字幕结果（Advanced）

接口说明

通过任务 id 获取已提交的 YouTube 视频字幕采集任务结果。

请求方式： GET请求地址：

https://api.seermartech.cn/v3/serp/youtube/video_subtitles/task_get/advanced/$id

$id 为任务唯一标识符，采用 UUID 格式。任务结果自创建后可在 30 天重复查询。

计费说明

该接口本身不重复收费。费用在创建任务时产生，后续在 30 天按 id 获取结果。

扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

路径参数

字段	类型	说明
id	string	任务唯一标识符，UUID 格式；可在任务创建后的 30 天用于随时获取结果

返回结果说明

接口返回 JSON 数据，顶层 tasks 数组，每个任务对象对应一次获取结果。

顶层字段

字段	类型	说明
version	string	当前 API 版本
status_code	integer	通用状态码
status_message	string	通用状态信息
time	string	执行耗时，单位秒
cost	float	本次请求总费用，单位 USD
tasks_count	integer	tasks 数组中的任务数量
tasks_error	integer	返回错误的任务数量
tasks	array	任务结果数组

tasks 数组字段

字段	类型	说明
id	string	任务 ID，UUID 格式
status_code	integer	任务状态码，范围通常为 10000-60000
status_message	string	任务状态信息
time	string	任务执行耗时，单位秒
cost	float	该任务费用，单位 USD
result_count	integer	result 数组中的结果数量
path	array	请求路径
data	object	与创建任务时传参数一致的请求参数
result	array	结果数组

result 数组字段

字段	类型	说明
video_id	string	POST 创建任务时传的视频 ID
se_domain	string	POST 创建任务时传的搜索引擎域名
location_code	integer	POST 创建任务时传的位置编码
language_code	string	POST 创建任务时传的语言编码
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	结果在整个 SERP 中的绝对排名
text	string	字幕文本；若设置了翻译语言，则为翻译后的字幕
start_time	integer	该字幕开始的秒数
end_time	integer	该字幕结束的秒数
duration_time	integer	字幕持续时长，单位秒

沙盒调试

可通过沙盒接口查看该端点可返回的完整字段结构，字段值为模拟数据，不产生费用。

沙盒地址：

https://sandbox.本平台.com/v3/serp/youtube/video_subtitles/task_get/advanced/00000000-0000-0000-0000-000000000000

状态码说明

建议在接时建立完整的异常处理机制，重点处理以下两层状态：

• 顶层 status_code：表示整个请求是否成功
• tasks[].status_code：表示单个任务是否成功

完整错误码请参考错误码文档。

请求示例

cURL

id="02261816-2027-0066-0000-c27d02864073"

curl --location --request GET "https://api.seermartech.cn/v3/serp/youtube/video_subtitles/task_get/advanced/${id}" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json"

Python

import requests

task_id = "02231256-2604-0066-2000-57133b8fc54e"
url = f"https://api.seermartech.cn/v3/serp/youtube/video_subtitles/task_get/advanced/{task_id}"

headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

response = requests.get(url, headers=headers)
print(response.json)

TypeScript

import axios from "axios";

const taskId = "02231256-2604-0066-2000-57133b8fc54e";

axios({
 method: "get",
 url: `https://api.seermartech.cn/v3/serp/youtube/video_subtitles/task_get/advanced/${taskId}`,
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json",
 },
})
 .then((response) => {
 // 输出任务结果
 console.log(response.data);
 })
 .catch((error) => {
 console.error(error);
 });

结果示例

{
 "version": "0.1.20220819",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0837 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "serp",
 "function": "task_get",
 "se": "youtube",
 "se_type": "video_subtitles",
 "language_code": "en",
 "location_code": 2840,
 "video_id": "Y8Wu4rSNJms",
 "priority": 2,
 "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": []
 }
 ]
 }
 ]
}

使用建议

• 通过任务提交接口创建字幕采集任务，再通过本接口按 id 获取结果
• 如果是批量任务处理，建议调用 /v3/serp/youtube/video_subtitles/tasks_ready 获取已完成任务，再逐个调用本接口
• 对 unsupported_language 做容处理，将不支持语言的数据直接后续分析流程
• 使用 start_time、end_time 可将字幕切片映射到视频时间轴，便于定位和摘要生成

实用场景

• 提取视频核心：按时间轴获取字幕文本，快速生成视频摘要、章节要点和提炼结果，降低人工观看成本
• 定位出现时刻：检索某个品牌词、产品词在字幕中的出现区间，帮助审核、竞品监测与视频证据留存
• 分析多语言传播：结合 origin_language 与 translate_language 获取翻译字幕，支持海外视频理解与本地化分析
• 构建视频索引：将字幕条目按 start_time、end_time库，建立可搜索的视频知识库，提升检索效率
• 监控视频主题表达：基于字幕文本做实体识别、感分析或主题聚类，品牌舆、行业研究与 SEO 选题洞察