获取 YouTube 视频（实时，高级版）

POST /v3/serp/youtube/video_info/live/advanced

本接口用于实时获取指定 YouTube 视频的数据。返回来自视频观看页，视频核心指标、信息，以及发布该视频的频道信息。

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

计费说明

该接口按请求计费，每次请求都会产生费用。 参考价约 ¥0.0960 / 次。

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

使用说明

• 请求体使用 UTF-8 编码的 JSON 格式；
• POST 请求体为 JSON 数组：[{ ... }]
• 实时 SERP 接口单次调用支持 1 个任务
• 频率限制：最多 2000 次 API 调用/分钟

---

请求参数

主要参数

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

---

请求示例

cURL

curl --location --request POST "https://api.seermartech.cn/v3/serp/youtube/video_info/live/advanced" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "language_code": "en",
 "location_code": 2840,
 "video_id": "vQXvyV0zIP4"
 }
]'

Python

import requests

url = "https://api.seermartech.cn/v3/serp/youtube/video_info/live/advanced"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}
data = [
 {
 "language_code": "en",
 "location_code": 2840,
 "video_id": "vQXvyV0zIP4"
 }
]

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

TypeScript

import axios from "axios";

async function getYoutubeVideoInfo {
 const response = await axios.post(
 "https://api.seermartech.cn/v3/serp/youtube/video_info/live/advanced",
 [
 {
 language_code: "en",
 location_code: 2840,
 video_id: "vQXvyV0zIP4",
 },
 ],
 {
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json",
 },
 }
 );

 console.log(response.data);
}

getYoutubeVideoInfo.catch(console.error);

---

响应结构

接口返回 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	任务唯一标识，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	与请求中提交的参数一致
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_video_info
items_count	integer	items 数组中的结果数量
items	array	结果项数组

items[] 字段

字段名	类型	说明
type	string	结果类型，固定为 youtube_video_info
rank_group	integer	同类型结果中的组排名
rank_absolute	integer	结果在整个 SERP 中的绝对排名
video_id	string	请求中的视频 ID
title	string	视频标题
url	string	视频链接
thumbnail_url	string	缩略图所在页面 URL
channel_id	string	发布该视频的频道 ID
channel_name	string	发布该视频的频道名称
channel_url	string	频道链接
channel_logo	string	频道 Logo 图片所在页面 URL
description	string	视频描述
views_count	integer	视频观看次数
likes_count	integer	视频点赞数
comments_count	integer	视频评论数
channel_subscribers_count	object	频道订人数信息
publication_date	string	视频展示的发布时间文本
timestamp	string	视频发布时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00
keywords	array	与视频的，即 YouTube tags
category	string	视频所属分类
is_live	boolean	是否为直播中视频
is_embeddable	boolean	是否支持嵌
duration_time	string	视频时长
duration_time_seconds	integer	视频时长（秒）
subtitles	array	字幕信息数组
streaming_quality	array	视频所有可用流媒体画质信息

channel_subscribers_count 字段

字段名	类型	说明
displayed_count	string	YouTube 页面展示的订数文本
count	integer	订人数数值

subtitles[] 字段

字段名	类型	说明
language	string	字幕语言
is_translatable	boolean	字幕是否支持翻译
is_auto_generated	boolean	是否为自动生成字幕

streaming_quality[] 字段

字段名	类型	说明
type	string	素类型，固定为 streaming_quality_element
label	string	画质标签
width	integer	视频宽度，像素
height	integer	视频高度，像素
bitrate	integer	视频码率
mime_type	string	视频媒体类型
fps	integer	帧率

---

响应示例

{
 "version": "0.1.20240801",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "5.0955 sec.",
 "cost": 0.006,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "serp",
 "function": "live",
 "se": "youtube",
 "se_type": "video_info",
 "language_code": "en",
 "location_code": 2840,
 "video_id": "vQXvyV0zIP4",
 "device": "desktop",
 "os": "windows"
 },
 "result": [
 {
 "items_count": 1,
 "items": [
 {
 "views_count": 5582811,
 "likes_count": 100646,
 "comments_count": 4367,
 "channel_subscribers_count": {
 "displayed_count": "478K subscribers",
 "count": 478000
 },
 "publication_date": "Premiered Jan 26, 2021",
 "timestamp": "2021-01-26 23:00:09 +00:00",
 "keywords": [],
 "category": "Autos & Vehicles",
 "is_live": false,
 "is_embeddable": true,
 "duration_time": "02:09",
 "duration_time_seconds": 129,
 "subtitles": null,
 "streaming_quality": []
 }
 ]
 }
 ]
 }
 ]
}

---

错误处理

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

1. 顶层状态：status_code、status_message
2. 任务状态：tasks[].status_code、tasks[].status_message

常见判断方式：

• 20000：请求成功
• 状态码：表示参数错误、权限问题、频控、服务异常等

完整错误码及说明请参考：/v3/appendix/errors

---

使用建议

• 若你已通过 YouTube SERP 接口获取视频列表，可直接取的视频 ID 调用本接口补；
• 建议同时保存 video_id、channel_id、timestamp，便于做视频与频道的历史快分析；
• is_live 可用于区分直播与普通视频；
• subtitles、streaming_quality 可能为空或 null，解析时需做好空值容。

实用场景

• 监控视频表现：定时抓取 views_count、likes_count、comments_count，评估视频传播效果与互动质量。
• 分析频道影响力：结合 channel_subscribers_count 与单视频表现，判断频道带量能力与稳定性。
• 识别直播：通过 is_live 快速区分直播与非直播视频，支持直播专题监测或竞品直播追踪。
• 评估可分发性：利用 is_embeddable、subtitles、streaming_quality 判断视频是否适合站外嵌、多语言传播或高质量投放。
• 构建视频标签库：提取 keywords、category、description 等字段，用于视频主题归类、研究和策略优化。