YouTube 视频任务创建

接口说明

通过本接口可提交 YouTube 视频采集任务，获取指定视频观看页中的详细信息视频核心指标、信息以及发布该视频的频道信息。

接口采用异步任务模式：创建任务后，平台返回唯一任务 ID。任务完成后，你可以通过该 ID 获取结果；也可以在创建任务时 postback_url 或 pingback_url，由平台在任务完成后主动通知你的服务端。

本接口支持两种执行优级：

• 1：普通优级（默认）
• 2：高优级（执行更快，费用更高）

请求地址

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

计费说明

平台在创建任务成功时扣费。

参考价约 ¥0.0288 / 次。 如使用高优级任务，费用会额外增加。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求规则

• 请求方法：POST
• 请求体格式：JSON 数组 [{ ... }]
• 编码：UTF-8
• 单次 POST 最多可提交 100 个任务
• 接口速率上限：2000 次 API 调用/分钟
• 如果单次请求中任务数 100，出部分将返回错误 40006

结果获取方式

你可以通过以下方式获取结果：

1. 使用任务返回的唯一标识 id，在后续结果接口中查询；
2. 创建任务时设置 pingback_url，任务完成后平台将向该地址发送 GET 通知；
3. 创建任务时设置 postback_url，任务完成后平台将以 gzip 压缩格式向该地址发送 POST 结果数据。

如果你的服务端在 10 秒未响应回调请求，连接会因时中止，任务结果会转对应的 “Tasks Ready” 列表，供你后续主动拉取。

---

主要请求参数

字段名	类型	说明
video_id	string	视频 ID。填。可从 YouTube 视频 URL 中获取，也可从 /v3/serp/youtube/organic/live/advanced/ 返回结果中的 youtube_video 项获取。示例：vQXvyV0zIP4
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 请求。支持在 URL 中使用 $id 和 $tag 变量，发送前会替换为值。示例：http://your-server.com/pingscript?id=$id 或 http://your-server.com/pingscript?id=$id&tag=$tag。注意：URL 中特殊字符会被编码，例如 # 会编码为 %23。
postback_url	string	结果回传地址。可选。任务完成后，平台会向该地址发送结果的 POST 请求，数据采用 gzip 压缩。支持在 URL 中使用 $id 和 $tag 变量。示例：http://your-server.com/postbackscript?id=$id 或 http://your-server.com/postbackscript?id=$id&tag=$tag。注意：URL 中特殊字符会被编码。
postback_data	string	回传数据类型。当指定 postback_url 时填。可选值：advanced

附加请求参数

字段名	类型	说明
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 对象会返回该值。

---

响应结构

接口返回 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	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	任务创建接口中该字段通常为 null

---

请求示例

cURL

curl --location --request POST "https://api.seermartech.cn/v3/serp/youtube/video_info/task_post" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "language_code": "en",
 "location_code": 2840,
 "video_id": "vQXvyV0zIP4"
 },
 {
 "language_name": "English",
 "location_name": "United States",
 "video_id": "vQXvyV0zIP4",
 "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_info/task_post"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

payload = [
 {
 # 示例 1：基础任务
 "language_code": "en",
 "location_code": 2840,
 "video_id": "vQXvyV0zIP4"
 },
 {
 # 示例 2：附带高优级、tag 和 pingback 回调
 "language_name": "English",
 "location_name": "United States",
 "video_id": "vQXvyV0zIP4",
 "priority": 2,
 "tag": "some_string_123",
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
 }
]

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

TypeScript

import axios from "axios";

const payload = [
 {
 // 示例 1：基础任务
 language_code: "en",
 location_code: 2840,
 video_id: "vQXvyV0zIP4",
 },
 {
 // 示例 2：高优级任务
 language_name: "English",
 location_name: "United States",
 video_id: "vQXvyV0zIP4",
 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_info/task_post",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json",
 },
 data: payload,
})
 .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.3229 sec.",
 "cost": 0.0018,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0023 sec.",
 "cost": 0.0018,
 "result_count": 0,
 "path": [
 "v3",
 "serp",
 "youtube",
 "video_info",
 "task_post"
 ],
 "data": {
 "api": "serp",
 "function": "task_post",
 "se": "youtube",
 "se_type": "video_info",
 "language_code": "en",
 "location_code": 2840,
 "video_id": "vQXvyV0zIP4",
 "device": "desktop",
 "os": "windows"
 },
 "result": null
 }
 ]
}

---

状态码与错误处理

• 20000：请求成功
• 20100：任务创建成功
• 40006：单次 POST 中任务数 100 个

建议在接时对以下建立健壮的异常处理机制：

• 顶层 status_code 非成功
• tasks 中部分任务创建失败
• 回调地址时或无法访问 -出任务上限、参数缺失、地区/语言无效等请求错误

完整错误码可参考 /v3/appendix/errors。

使用建议

• 批量提交时，请将单次请求控制在 100 个任务
• 如果追求更快返回速度，可使用 priority=2，但需费用变化
• 如需构建异步数据管道，建议结合 tag、pingback_url 或 postback_url 使用
• 如果使用 postback_url，务同步传 postback_data: "advanced"

实用场景

• 采集单个视频：获取指定 YouTube 视频的核心信息与频道信息，便于做竞品视频研究和素材分析。
• 监控重点视频表现：持续提交目标视频任务，跟踪视频页键信息变化，为运营复盘提供依据。
• 回填视频数据：将视频标题、频道等写库，提升视频资产管理与检索效率。
• 分析竞品频道策略：围绕竞品热视频批量建立任务，识别选题方向和频道布局。
• 构建异步采集流程：结合 pingback_url 或 postback_url 自动接收结果，减少轮询查询成本并提升处理效率。