获取 Google AI Mode SERP 高级结果（按任务 ID）

接口说明

通过任务 ID 获取 Google AI Mode SERP 的高级结果。

请求地址

GET https://api.seermartech.cn/v3/serp/google/ai_mode/task_get/advanced/$id

说明：

• $id：任务唯一标识符，UUID 格式
• 任务结果自提交后可在 30 天 多次获取

计费说明

本接口本身不会重复扣费，在创建任务时扣费。任务提交成功后，后续 30 天按任务 ID 获取结果。

从响应示例看，平台单次任务成本为 USD 0.004，折算后：

• 参考价约 ¥0.0640 / 次

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

请求参数

路径参数

字段	类型	说明
id	string	任务 ID，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	与创建任务时 POST 请求中一致的参数集合。
result	array	获取结果数组。

result[] 字段

字段	类型	说明
keyword	string	创建任务时的。返回时会解码 %##， + 会被解码为空格。
type	string	创建任务时指定的搜索引擎类型。
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 / null	搜索引擎自动纠错信息；如果未发生纠错，可能为 null。
refinement_chips	object / null	搜索细化建议模块；没有则为 null。
item_types	array	当前 SERP 中出现的结果类型列表。当前可能：ai_overview。
se_results_count	integer	SERP 结果总数。
items_count	integer	items 数组中的结果数量。
items	array	SERP 中解析出的结果项。

结果对象详解

spell

字段	类型	说明
keyword	string	搜索引擎纠错后的。
type	string	自动纠错类型。可能值：did_you_mean、showing_results_for、no_results_found_for、including_results_for。

refinement_chips

字段	类型	说明
type	string	固定为 refinement_chips。
xpath	string	素的 XPath。
items	array	细化选项列表。

refinement_chips.items[]

字段	类型	说明
type	string	固定为 refinement_chips_element。
title	string	选项标题。
url	string	带细化参数的搜索链接。
domain	string	SERP 中展示的域名。
options	array	更进一步的细化选项。

refinement_chips.items[].options[]

字段	类型	说明
type	string	固定为 refinement_chips_option。
title	string	选项标题。
url	string	带细化参数的搜索链接。
domain	string	SERP 中展示的域名。

items[] 支持的结果类型

当前该端点主要返回 ai_overview 类型结果。

ai_overview

字段	类型	说明
type	string	固定为 ai_overview。
rank_group	integer	相同 type 结果中的组排名。
rank_absolute	integer	SERP 中的绝对排名。
page	integer	所在 SERP 页码。
position	string	素在 SERP 中的位置，可能值：left、right。
xpath	string	素的 XPath。
asynchronous_ai_overview	boolean	是否异步加载。true 表示异步加载；false 表示从缓存加载。
markdown	string	ai_overview 的 Markdown 格式。
items	array	AI Overview部子列表。
references	array	与当前 AI Overview 的补参考来源。
rectangle	object / null	结果块在页面中的坐标和尺寸；当创建任务时设置 calculate_rectangles=true 才会返回。

---

ai_overview.items[] 可能出现的子类型

1）ai_overview_element

通用文本块。

字段	类型	说明
type	string	固定为 ai_overview_element。
position	string	素位置：left 或 right。
title	string	素标题。
text	string	素文本或描述。
markdown	string	Markdown 格式。
links	array / null	素中展示的网站链接。
images	array / null	素中的图片。
references	array / null	用于生成该的参考页面。

links[]

字段	类型	说明
type	string	固定为 link_element。
title	string	链接锚文本。
description	string	链接描述。
url	string	链接地址。
domain	string	链接域名。

images[]

字段	类型	说明
type	string	固定为 images_element。
alt	string	图片 alt 文本。
url	string	页面 URL。
image_url	string	图片 URL。若源站不可用，可能返回本平台存储地址。

references[]

字段	类型	说明
type	string	固定为 ai_overview_reference。
source	string	参考来源名称或标题。
domain	string	参考来源域名。
url	string	参考页面 URL。
title	string	参考页面标题。
text	string	用于生成该的页面文本片段。

2）ai_overview_video_element

视频结果块。

字段	类型	说明
type	string	固定为 ai_overview_video_element。
position	string	素位置：left 或 right。
title	string	视频标题。
snippet	string	视频补说明。
url	string	视频链接。
domain	string	托管视频的网站域名。
image_url	string	视频缩略图地址。
source	string	视频来源名称。
date	string	视频发布时间或收录日期，例如 Apr 26, 2024。
timestamp	string	UTC 时间戳，格式：yyyy-mm-dd hh-mm-ss +00:00。

3）ai_overview_table_element

表格结果块。

字段	类型	说明
type	string	固定为 ai_overview_table_element。
position	string	素位置：left 或 right。
markdown	string	表格的 Markdown 表达。
table	object	表格对象，表头和表体。
references	array	与该表格的参考来源。

table

字段	类型	说明
table_header	array	表头。
table_content	array	表格，每个数组代表一行。

4）ai_overview_expanded_element

展开式块。

字段	类型	说明
type	string	固定为 ai_overview_expanded_element。
position	string	素位置：left 或 right。
title	string	素标题。
text	string	素附加文本。
components	array	展开块中的组件列表。

components[]

字段	类型	说明
type	string	固定为 ai_overview_expanded_component。
title	string	组件标题。
text	string	组件文本。
markdown	string	Markdown 格式文本。
images	array / null	组件中的图片。
links	array / null	组件中的站点链接。

5）ai_overview_shopping

购物结果块。

字段	类型	说明
type	string	固定为 ai_overview_shopping。
position	string	素位置：left 或 right。
title	string	素标题。
markdown	string	购物的 Markdown 文本。
items	array	商品列表。
references	array	与该购物结果的补参考来源。

ai_overview_shopping.items[]

字段	类型	说明
type	string	固定为 ai_overview_shopping_element。
product_id	string	Google Shopping 中的唯一商品 ID。
data_docid	string	SERP 数据唯一 ID。
gid	string	Google Shopping局商品标识。
title	string	商品标题。
url	string	商品或筛选链接。
domain	string	SERP 展示域名。
rating	object / null	商品评分。
price	object / null	商品价格信息。
seller	string	卖家名称。
snippet	string	结果补说明。
marketplace	string	商家账户提供方，例如某电商平台聚合。
marketplace_url	string	商家账户提供方 URL。
image_url	string	商品图片地址。

rating

字段	类型	说明
rating_type	string	评分类型，可见值：Max5、Percents、CustomMax。
value	float	评分值。
votes_count	integer	评论/评分数量。
rating_max	integer	当前评分体系下的最大值。

price

字段	类型	说明
current	float	当前价格。
regular	float	原价。
max_value	float	最高价格。
currency	string	价格币种，ISO 代码。
is_price_range	boolean	是否为价格区间。
displayed_price	string	搜索结果中展示的原始价格字符串。

ai_overview.references[]

字段	类型	说明
type	string	固定为 ai_overview_reference。
source	string	参考来源名称或标题。
domain	string	参考域名。
url	string	参考页面链接。
title	string	参考页面标题。
text	string	参与生成的页面文本片段。

rectangle

字段	类型	说明
x	integer	左上角 x 坐标。
y	integer	左上角 y 坐标。
width	integer	素宽度，像素。
height	integer	素高度，像素。

Sandbox

你可以使用以下 Sandbox 地址查看该端点可能返回的完整字段结构，返回值为模拟数据，不扣费：

GET https://sandbox.seermartech.cn/v3/serp/google/ai_mode/task_get/advanced/00000000-0000-0000-0000-000000000000

该 Sandbox 响应会尽可能此端点支持的各类 SERP素及字段，便于联调与字段映射。

调用示例

cURL

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

curl --location --request GET "https://api.seermartech.cn/v3/serp/google/ai_mode/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/google/ai_mode/task_get/advanced/{task_id}"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

response = requests.get(url, headers=headers)
print(response.status_code)
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/google/ai_mode/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);
 });

结合 tasks_ready 获取已完成任务

接中，通常通过 /v3/serp/google/ai_mode/tasks_ready 获取已完成任务，再按任务 ID 或返回的高级结果地址逐个获取结果。

Python 示例

import requests

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

# 1. 获取已完成任务列表
ready_url = "https://api.seermartech.cn/v3/serp/google/ai_mode/tasks_ready"
ready_resp = requests.get(ready_url, headers=headers).json

results = []

if ready_resp.get("status_code") == 20000:
 for task_group in ready_resp.get("tasks", []):
 for task in task_group.get("result", []) if isinstance(task_group, dict) else []:
 endpoint = task.get("endpoint_advanced")
 task_id = task.get("id")

 # 2. 直接用 endpoint_advanced 获取高级结果
 if endpoint:
 r = requests.get(f"https://api.seermartech.cn{endpoint}", headers=headers)
 results.append(r.json)

 # 3. 或自行按 id 拼接请求地址
 # if task_id:
 # r = requests.get(
 # f"https://api.seermartech.cn/v3/serp/google/ai_mode/task_get/advanced/{task_id}",
 # headers=headers
 # )
 # results.append(r.json)

print(results)

响应示例

{
 "version": "0.1.20260223",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "12.8697 sec.",
 "cost": 0.004,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "serp",
 "function": "task_get",
 "se": "google",
 "se_type": "ai_mode",
 "language_name": "English",
 "location_name": "London,England,United Kingdom",
 "keyword": "iphone 16 price comparison",
 "device": "desktop",
 "os": "windows"
 },
 "result": [
 {
 "se_results_count": 0,
 "items_count": 1,
 "items": [
 {
 "type": "ai_overview",
 "markdown": "示例已省略，返回通常 AI Overview 的 markdown、子、参考来源、购物块、表格块等详细结构。",
 "items": [
 {
 "type": "ai_overview_element",
 "position": "left",
 "title": "UK Price Comparison by Model (SIM-Free)",
 "text": "Retail prices in the UK vary slightly between the official Apple Store and major electronics retailers.",
 "markdown": "Retail prices in the UK vary slightly between the official Apple Store and major electronics retailers.",
 "links": null,
 "images": null,
 "references": null
 },
 {
 "type": "ai_overview_shopping",
 "position": "left",
 "title": null,
 "markdown": "购物摘要",
 "items": []
 },
 {
 "type": "ai_overview_table_element",
 "position": "left",
 "markdown": "| Model | 128GB | 256GB | 512GB | 1TB |",
 "table": {
 "table_header": null,
 "table_content": []
 }
 }
 ],
 "references": [],
 "rectangle": null
 }
 ]
 }
 ]
 }
 ]
}

状态码与错误处理

• 顶层 status_code 表示整个请求的执行状态
• tasks[].status_code 表示单个任务的执行状态
• 建议同时校验：
• 顶层 status_code == 20000
• 任务级 status_code 是否成功
• result 是否存在且非空

常见处理建议：

1. 若顶层状态码非成功，直接按请求失败处理
2. 若顶层成功但任务级状态码异常，按单任务失败记录日志
3. 若 result 为空，说明任务可能尚未完成、已失效或无可用结果
4. 建议保留原始 status_message 便于排查问题

使用建议

• 创建任务，再通过 /v3/serp/google/ai_mode/tasks_ready 轮询已完成任务
• 对 ai_overview.markdown 和 items[] 同时解析：前适合快速展示，后适合结构化库
• 若需要页面可视化定位，请在创建任务时启用 calculate_rectangles=true
• 对 references、shopping、table、video 等不同子结构做类型分发处理

实用场景

• 抓取 AI Overview 摘要：提取搜索结果中的 AI 回答主体，用于监控品牌词、产品词和行业问题词的答案呈现方式。
• 解析引用来源：识别 AI Overview 采用了哪些参考页面和域名，评估品牌是否被搜索引擎引用，投放与外链策略。
• 监控购物推荐位：提取 ai_overview_shopping 中的商品、价格、评分和卖家信息，分析商品在 AI 搜索中的与竞品分布。
• 抽取表格与结构化对比信息：识别 ai_overview_table_element 中的参数对比表、价格表、规格表，便于做竞品报和差距分析。
• 还原 SERP 版面布局：结合 rank_absolute、position 和 rectangle 字段，分析 AI 模块在页面中的位置与可见性，为 CTR 和 SEO 展示研究提供依据。