提交 YouTube 视频字幕采集任务

POST /v3/serp/youtube/video_subtitles/task_post

接口说明

通过本接口可提交 YouTube 视频字幕采集任务，获取指定视频观看页中的字幕。结果通常字幕文本、字幕语言以及字幕在视频中的时间长度等信息。

接口支持两种执行优级：

• 1：普通优级（默认）
• 2：高优级

高优级任务执行更快，但费用更高。

请求方式

POST https://api.seermartech.cn/v3/serp/youtube/video_subtitles/task_post

计费说明

该接口在创建任务时扣费。

参考价需结合参考单价换算，扣费以响应头 X-SeerMarTech-Charge-CNY 为准。 如使用高优级，费用会高于普通优级。

请求规则

• 请求体为 UTF-8 编码的 JSON
• POST 请求体格式为 JSON 数组：[{ ... }]
• 单次 POST 最多可提交 100 个任务
• 每分钟最多可发起 2000 次 API 调用
• 若单次请求中任务数 100，出部分会返回错误码 40006

任务提交后，可通过返回的唯一任务 ID 获取结果。 如果在创建任务时指定了 postback_url 或 pingback_url，本平台会在任务完成后主动通知你的服务端。

回调说明

• pingback_url：任务完成后，向你指定的地址发送 GET 请求
• postback_url：任务完成后，向你指定的地址发送带结果的 POST 请求，结果为 gzip 压缩格式

你可以在回调 URL 中使用：

• $id：任务 ID
• $tag：你提交的自定义标记（会进行 URL 编码）

例如：

• https://your-server.com/pingscript?id=$id
• https://your-server.com/pingscript?id=$id&tag=$tag

注意：

• pingback_url 和 postback_url 中的特殊字符会被 URL 编码
• 例如 # 会被编码为 %23
• 若你的服务端在 10 秒未响应，连接会因时中断，任务会 /v3/serp/youtube/video_subtitles/tasks_ready/ 列表你后续拉取

---

主要参数

字段	类型	说明
video_id	string	填。视频 ID。可从 YouTube 视频 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
priority	integer	可选。任务优级：1 = 普通优级（默认），2 = 高优级。高优级会产生额外费用。
device	string	可选。设备类型。支持：desktop
pingback_url	string	可选。任务完成后的通知地址，系统将向该地址发送 GET 请求。支持 $id 和 $tag 变量。
postback_url	string	可选。任务完成后的结果回传地址，系统将向该地址发送结果的 POST 请求（gzip 压缩）。支持 $id 和 $tag 变量。
postback_data	string	当指定 postback_url 时填。表示发送到你服务端的数据类型。支持：advanced

附加参数

字段	类型	说明
location_name	string	当未传 location_code 时填。搜索引擎地区名。若传此字段，则无需传 location_code。示例：United States
language_name	string	当未传 language_code 时填。搜索引擎语言名。若传此字段，则无需传 language_code。示例：English
os	string	可选。设备操作系统，可选：windows、macos。默认值：windows
tag	string	可选。自定义任务标识，最大 255 字符。便于你在结果中做任务映射。该值会出现在响应的 data 对象中。
subtitles_language	string	可选。原始字幕语言代码。可从 YouTube 视频信息接口结果中获取。
subtitles_translate_language	string	可选。目标翻译字幕语言代码。支持大量语言代码，例如：en、zh-Hans、zh-Hant、ja、ko、fr、de、es、it、ru 等。

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	通用状态说明
time	string	执行耗时，单位秒
cost	float	本次请求总费用，单位 USD
tasks_count	integer	tasks 数组中的任务数量
tasks_error	integer	tasks 数组中返回错误的任务数量
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	结果数组；对于任务提交接口，此处通常为 null

---

请求示例

cURL

curl --location --request POST "https://api.seermartech.cn/v3/serp/youtube/video_subtitles/task_post" \
 --header "Authorization: Bearer smt_live_YOUR_KEY" \
 --header "Content-Type: application/json" \
 --data-raw '[
 {
 "language_code": "en",
 "location_code": 2840,
 "video_id": "Y8Wu4rSNJms"
 },
 {
 "language_name": "English",
 "location_name": "United States",
 "video_id": "Y8Wu4rSNJms",
 "priority": 2,
 "tag": "some_string_123",
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
 }
 ]'

Python

import requests

url = "https://api.seermartech.cn/v3/serp/youtube/video_subtitles/task_post"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

data = [
 {
 # 基础任务：指定语言、地区和视频 ID
 "language_code": "en",
 "location_code": 2840,
 "video_id": "Y8Wu4rSNJms"
 },
 {
 # 高优级任务：更快执行，并通过 pingback 回调通知
 "language_name": "English",
 "location_name": "United States",
 "video_id": "Y8Wu4rSNJms",
 "priority": 2,
 "tag": "some_string_123",
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
 }
]

response = requests.post(url, headers=headers, json=data)
print(response.json)

TypeScript

import axios from "axios";

const postData = [
 {
 language_code: "en",
 location_code: 2840,
 video_id: "Y8Wu4rSNJms",
 },
 {
 language_name: "English",
 location_name: "United States",
 video_id: "Y8Wu4rSNJms",
 priority: 2,
 tag: "some_string_123",
 pingback_url: "https://your-server.com/pingscript?id=$id&tag=$tag",
 },
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/serp/youtube/video_subtitles/task_post",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json",
 },
 data: postData,
})
 .then((response) => {
 // 返回的是任务提交结果，字幕需后续通过任务结果接口获取
 console.log(response.data);
 })
 .catch((error) => {
 console.error(error.response?.data || error.message);
 });

---

响应示例

{
 "version": "0.1.20220819",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0983 sec.",
 "cost": 0.0036,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "serp",
 "function": "task_post",
 "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": null
 }
 ]
}

---

状态与错误处理

• 顶层 status_code = 20000 表示请求成功
• 单个任务的执行状态需查看 tasks[].status_code
• 如果单次 POST过 100 个任务，出部分会返回 40006
• 建议业务侧建立完整的异常处理机制，覆盖：
• 请求参数缺失
• 回调时
• 单任务失败
• 批量任务部分成功、部分失败

---

结果获取方式

提交成功后，可通过以下方式获取结果：

1. 使用响应中的任务 id 轮询对应结果接口
2. 在创建任务时 pingback_url
3. 在创建任务时 postback_url 与 postback_data=advanced

注意：本接口只是创建任务，提交成功时 result 通常为 null，字幕数据需任务完成后再获取。

实用场景

• 采集视频字幕：抓取指定 YouTube 视频的完整字幕文本，用于视频理解、语义分析和知识提炼。
• 分析多语言字幕覆盖：检查视频是否提供原始字幕及翻译字幕，评估海外本地化质量。
• 监控竞品视频话术：批量提交竞品频道热视频任务，提取字幕以分析营销表达、产品卖点和用户沟通方式。
• 构建视频 SEO 语料库：将字幕文本沉淀为可检索语料，支持挖掘、主题聚类和优化。
• 验证字幕翻译质量：指定 subtitles_translate_language 获取目标语言字幕，评估自动翻译效果与跨语言传播适度。