SeerMarTech API 文档

主题

创建 YouTube 自然搜索任务 ​

POST /v3/serp/youtube/organic/task_post

接口说明 ​

通过本接口可提交 YouTube 自然搜索采集任务。接口返回指定地区与语言下的 YouTube 搜索结果，默认可获取前 20 个结果区块。

  • 请求方式：POST
  • 接口地址：https://api.seermartech.cn/v3/serp/youtube/organic/task_post

支持两种执行优级：

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

任务创建成功后，可通过返回的任务 id 获取结果；也可以在创建任务时 pingback_url 或 postback_url，由本平台在结果就绪后主动通知或推送结果。

计费说明 ​

在创建任务时计费。

  • 普通任务：扣费以响应头 X-SeerMarTech-Charge-CNY 为准
  • 高优级任务：会产生额外费用，扣费以响应头 X-SeerMarTech-Charge-CNY 为准

深度抓取：

  • block_depth 默认值为 20
  • 按每 20 个结果区块 作为一个计费单位
  • 如果 block_depth > 20，且搜索引擎返回了更多结果，可能产生额外扣费
  • 如果设置的深度高于返回数量，出部分会自动返还到账户余额

请求限制 ​

  • 每分钟最多可发起 2000 次 API 调用
  • 每次 POST 请求最多 100 个任务
  • 如果单次请求中任务数 100，出部分将返回错误 40006

请求体格式 ​

所有 POST 数据使用 UTF-8 编码的 JSON 格式，并按数组传参：

json
[
 {
 "language_code": "en",
 "location_code": 2840,
 "keyword": "audi"
 }
]

结果获取方式 ​

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

  1. 使用任务 id 轮询获取结果 2.置 pingback_url：任务完成后，本平台向该地址发送 GET 请求 3.置 postback_url：任务完成后，本平台向该地址发送带有结果数据的 POST 请求，数据采用 gzip 压缩

注意事项：

  • 如果您的服务器在 10 秒未响应，连接会因时中断
  • 此类任务会被转 /v3/serp/youtube/organic/tasks_ready/ 列表
  • 错误码和错误信息取决于您的服务器

主要参数 ​

字段名类型说明
keywordstring填。搜索，最长 700 个字符。请求中的 %## 会被解码，字符 + 会被解码为空格。如果中需要保留 %，请写为 %25；如需保留 +，请写为 %2B。
location_codeinteger当未提供 location_name 时填。搜索地区代码。若已传此字段，则无需再传 location_name。可通过 /v3/serp/youtube/locations 获取地区列表。示例：2840
language_codestring当未提供 language_name 时填。搜索语言代码。若已传此字段，则无需再传 language_name。可通过 /v3/serp/youtube/languages 获取语言列表。示例：en
devicestring可选。设备类型。可选值：desktop、mobile
priorityinteger可选。任务优级：1 普通优级（默认），2 高优级
pingback_urlstring可选。任务完成后的通知地址，本平台会向该地址发送 GET 请求。可使用 $id 作为任务 ID 变量，$tag 作为 URL 编码后的标签变量。示例：http://your-server.com/pingscript?id=$id 或 http://your-server.com/pingscript?id=$id&tag=$tag。注意：特殊字符会被 URL 编码，例如 # 会编码为 %23
postback_urlstring可选。任务完成后的结果回传地址，本平台会向该地址发送带 gzip 压缩结果的 POST 请求。支持 $id 与 $tag 变量。注意：特殊字符会被 URL 编码
postback_datastring当指定 postback_url 时填。定义回传的数据类型。当前支持：advanced

附加参数 ​

字段名类型说明
location_namestring当未提供 location_code 时填。完整地区名称。若已传此字段，则无需再传 location_code。可通过 /v3/serp/youtube/locations 获取。示例：United States
language_namestring当未提供 language_code 时填。完整语言名称。若已传此字段，则无需再传 language_code。可通过 /v3/serp/youtube/languages 获取。示例：English
osstring可选。设备操作系统。若 device=desktop，可选 windows、macos，默认 windows；若 device=mobile，可选 android、ios，默认 android
tagstring可选。自定义任务标识，最长 255 个字符。可用于请求与结果匹，返回结果中的 data 对象会带回该值
search_paramstring可选。附加搜索参数。示例：sp=EgIQAg%253D%253D
block_depthinteger可选。SERP 解析深度，即抓取的结果区块数。默认 20，最大 700

响应结构 ​

接口返回 JSON 对象 tasks 数组，用于描述本次提交的任务状态。

顶层字段 ​

字段名类型说明
versionstring当前 API 版本
status_codeinteger通用状态码，完整列表参考 /v3/appendix/errors
status_messagestring通用状态信息，完整列表参考 /v3/appendix/errors
timestring执行耗时，单位秒
costfloat本次请求总费用，单位 USD
tasks_countintegertasks 数组中的任务数量
tasks_errorintegertasks 数组中返回错误的任务数量
tasksarray任务数组

tasks 数组字段 ​

字段名类型说明
idstring任务唯一标识，UUID 格式
status_codeinteger任务状态码，范围通常为 10000-60000
status_messagestring任务状态说明
timestring任务处理耗时，单位秒
costfloat单个任务费用，单位 USD
result_countintegerresult 数组中的数量
patharray接口路径
dataobject与提交请求中一致的任务参数
resultarray | null结果数组。对于 task_post 接口，该字段通常为 null

请求示例 ​

cURL ​

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

Python ​

python
import requests

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

# POST 请求体是 JSON 数组
payload = [
 {
 "language_code": "en",
 "location_code": 2840,
 "keyword": "audi"
 },
 {
 "language_name": "English",
 "location_name": "United States",
 "keyword": "audi",
 "priority": 2,
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
 }
]

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

TypeScript ​

typescript
import axios from "axios";

const postArray = [
 {
 language_code: "en",
 location_code: 2840,
 keyword: "audi"
 },
 {
 language_name: "English",
 location_name: "United States",
 keyword: "audi",
 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/organic/task_post",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 },
 data: postArray
})
 .then((response) => {
 // 返回任务提交结果
 console.log(response.data);
 })
 .catch((error) => {
 console.error(error.response?.data || error.message);
 });

响应示例 ​

json
{
 "version": "0.1.20220819",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0711 sec.",
 "cost": 0.0012,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0023 sec.",
 "cost": 0.0012,
 "result_count": 0,
 "path": [
 "v3",
 "serp",
 "youtube",
 "organic",
 "task_post"
 ],
 "data": {
 "api": "serp",
 "function": "task_post",
 "se": "youtube",
 "se_type": "organic",
 "language_code": "en",
 "location_code": 2840,
 "keyword": "audi",
 "priority": 2,
 "device": "desktop",
 "os": "windows"
 },
 "result": null
 }
 ]
}

状态码与错误处理 ​

建议在接时同时处理以下两层状态：

  1. HTTP 状态码
  2. 响应体中的 status_code / status_message

重点注意：

  • 顶层 status_code=20000 表示请求成功受理
  • 单个任务仍可能在 tasks 数组中返回独立错误
  • 若单次请求任务数 100，出部分会返回 40006
  • 完整错误码列表可参考 /v3/appendix/errors

使用建议 ​

  • 优使用 location_code 和 language_code，比名称字段更稳定
  • 批量提交时，每次控制在 100 个任务
  • 需要更快返回时可使用 priority=2
  • 需要异步接收结果时，优 postback_url 或 pingback_url
  • 如果业务对费用敏感，请谨提高 block_depth

实用场景 ​

  • 监控品牌词视频：定期提交品牌词、产品词任务，跟踪 YouTube 自然结果中的视频排名与展示结构变化。
  • 分析竞品视频搜索占位：围绕竞品品牌词和核心功能词抓取结果，识别竞品在视频搜索场景中的覆盖能力。
  • 评估地区化视频 SEO 表现：按不同 location_code 和 language_code 创建任务，对比同一在不同国家和语言下的结果差异。
  • 追踪移动端与桌面端差异：结合 device 与 os 参数，分析同一搜索词在不同终端上的结果排序和形态差异。
  • 批量构建视频观察集：通过批量任务方式持续采集一组的 YouTube SERP 数据，为视频选题和 SEO 策略提供依据。

统一入口：官网 · LLM API · 控制台

© 2026 SeerMarTech · GEO · SEO 营销数据 API