提交 Google AI Mode SERP 任务

接口概述

该接口用于创建 Google 搜索 AI Mode 结果抓取任务。任务创建后，本平台会异步执行采集，你可以通过任务 id 轮询获取结果，也可以在创建任务时 pingback_url 或 postback_url，由本平台在任务完成后主动通知或回传结果。

接口支持两种执行优级：

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

高优级通常能更快返回结果，但会产生额外费用。

请求地址

POST https://api.seermartech.cn/v3/serp/google/ai_mode/task_post

计费与调用限制

在创建任务时扣费
实扣费以响应头 X-SeerMarTech-Charge-CNY 为准
参考价约 ¥0.0192 / 次
若使用高优级 priority=2，费用会更高
若启用 calculate_rectangles=true，单任务费用会变为 2 倍

调用限制：

每分钟最多 2000 次 API 调用
每个 POST 请求最多 100 个任务 -过 100 个任务时，出部分将返回错误 40006

请求格式

请求方法：POST
Content-Type：application/json
编码：UTF-8
请求体为 JSON 数组：[{ ... }]

结果获取方式

任务创建成功后，可通过以下方式获取结果：

使用返回的唯一任务标识 id 获取结果
创建任务时设置 pingback_url，任务完成后本平台向该地址发送 GET 通知
创建任务时设置 postback_url，任务完成后本平台向该地址发送携带结果的 POST 请求，结果为 gzip 压缩格式

注意事项：

如果你的服务器在 10 秒未响应，连接会因时被中断
此类任务会转 /v3/serp/google/ai_mode/tasks_ready/ 列表，可后续统一拉取
回调失败时，错误码和错误信息取决于你的服务端

主要参数

字段名	类型	说明
`keyword`	string	填。搜索，最长 `700` 个字符。`%##` 会被解码，字符 `+` 会被解码为空格。如果中需要字面量 `%`，请写为 `%25`；如果需要字面量 `+`，请写为 `%2B`。
`location_code`	integer	当未提供 `location_name` 或 `location_coordinate` 时填。搜索地区代码。使用该字段时，无需再传 `location_name` 或 `location_coordinate`。可通过 `/v3/serp/google/locations` 获取可用地区。注意：AI Mode 在部分国家/地区可用。
`language_code`	string	当未提供 `language_name` 时填。搜索语言代码。使用该字段时，无需再传 `language_name`。可通过 `/v3/serp/google/ai_mode/languages` 获取可用语言。
`priority`	integer	可选。任务优级：`1` = 普通优级（默认），`2` = 高优级。高优级会额外扣费。
`device`	string	可选。设备类型，可选值：`desktop`、`mobile`。默认值：`desktop`。
`pingback_url`	string	可选。任务完成通知地址。本平台会向该地址发起 GET 请求。可使用 `$id` 作为任务 ID 变量，`$tag` 作为经过 URL 编码的 tag 变量。例如：`https://your-server.com/pingscript?id=$id&tag=$tag`。注意：特殊字符会被 URL 编码，例如 `#` 会转成 `%23`。
`postback_url`	string	可选。结果回传地址。任务完成后，本平台会以 POST 方式将 `gzip` 压缩结果发送到该地址。支持 `$id` 和 `$tag` 变量替换。
`postback_data`	string	当指定 `postback_url` 时填。表示回传的数据类型，需与设置任务时使用的结果类型对应。可选值：`advanced`、`html`。

附加参数

字段名	类型	说明
`location_name`	string	当未提供 `location_code` 或 `location_coordinate` 时填。搜索地区名。使用该字段时，无需再传 `location_code` 或 `location_coordinate`。可通过 `/v3/serp/google/locations` 获取可用地区。
`language_name`	string	当未提供 `language_code` 时填。搜索语言名。使用该字段时，无需再传 `language_code`。可通过 `/v3/serp/google/ai_mode/languages` 获取可用语言。
`os`	string	可选。设备操作系统。若 `device=desktop`，可选 `windows`、`macos`，默认 `windows`；若 `device=mobile`，可选 `android`、`ios`，默认 `android`。
`tag`	string	可选。自定义任务标识，最长 `255` 个字符。可用于业务侧请求与结果。返回结果中的 `data` 对象会原样带回该值。
`calculate_rectangles`	boolean	可选。是否计算高级结果中各 SERP素的像素位置。像素排名表示结果片段相对屏幕左上角的距离。默认 `false`。若设为 `true`，单任务费用乘以 2。
`browser_screen_width`	integer	可选。浏览器屏幕宽度，范围 `240-9999`。默认值：桌面端 `1920`；Android 移动端 `360`；iOS 移动端 `375`。使用该参数前需设置 `calculate_rectangles=true`。
`browser_screen_height`	integer	可选。浏览器屏幕高度，范围 `240-9999`。默认值：桌面端 `1080`；Android 移动端 `640`；iOS 移动端 `812`。使用该参数前需设置 `calculate_rectangles=true`。
`browser_screen_resolution_ratio`	integer	可选。屏幕分辨率比例，范围 `0.5-3`。默认值：桌面端 `1`；Android 移动端 `3`；iOS 移动端 `3`。使用该参数前需设置 `calculate_rectangles=true`。
`location_coordinate`	string	当未提供 `location_name` 或 `location_code` 时填。GPS 坐标，格式为 `"latitude,longitude,zoom"`。若未指定 `zoom`，默认使用 `9z`。`latitude` 与 `longitude` 最多 `7` 位小数；`zoom` 取值范围 `4z-18z`。示例：`52.6178549,-155.352142,18z`

返回结果说明

接口返回 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	任务唯一标识，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

bash

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

# 请求体为 JSON 数组
payload = [
 {
 "language_code": "en",
 "location_code": 2840,
 "keyword": "what is google ai mode"
 },
 {
 "language_name": "English",
 "location_name": "United States",
 "keyword": "what is google ai mode",
 "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

typescript

import axios from "axios";

const payload = [
 {
 language_code: "en",
 location_code: 2840,
 keyword: "what is google ai mode"
 },
 {
 language_name: "English",
 location_name: "United States",
 keyword: "what is google ai mode",
 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/google/ai_mode/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);
 });

响应示例

json

{
 "version": "0.1.20250526",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0764 sec.",
 "cost": 0.0012,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "12345678-1234-1234-1234-1234567890ab",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0021 sec.",
 "cost": 0.0012,
 "result_count": 0,
 "path": [
 "v3",
 "serp",
 "google",
 "ai_mode",
 "task_post"
 ],
 "data": {
 "api": "serp",
 "function": "task_post",
 "se": "google",
 "se_type": "ai_mode",
 "language_code": "en",
 "location_code": 2840,
 "keyword": "what is google ai mode",
 "device": "desktop",
 "os": "windows"
 },
 "result": null
 }
 ]
}

常见状态与错误说明

代码	含义
`20000`	请求成功
`20100`	任务创建成功
`40006`	单次 POST 中任务数量 `100` 个，出部分被拒绝
状态码	请结合统一错误码体系处理

建议重点处理以下异常：

-填参数缺失

location_code / location_name / location_coordinate 互斥或缺失
language_code / language_name 缺失
回调地址不可达或时
AI Mode 在指定国家/地区不可用 -过单请求任务数或分钟级调用限制

使用建议

批量提交时，每次控制在 100 个任务
如需更快时效，可对高价值使用 priority=2
若你的业务依赖异步回传，优 postback_url
若只需要完成通知，可使用 pingback_url
需要做可视化排名分析时，再启用 calculate_rectangles=true，不费用

实用场景

监控 AI 搜索露出：跟踪目标在 Google AI Mode 中是否触发 AI 结果，帮助评估品牌与在新型搜索结果页中的可见性。
批量采集重点：按国家、语言、设备批量创建任务，持续观察不同市场的 AI 搜索表现，为 SEO 提供依据。
对比移动端与桌面端结果差异：分别设置 device 和 os，分析 AI Mode 在不同终端上的结果结构差异，优化多端策略。
构建异步抓取流水线：结合 pingback_url 或 postback_url 自动接收任务完成通知或结果回传，降低轮询成本并提升处理效率。
分析结果页面像素位置：启用 calculate_rectangles 后获取 SERP素像素定位，用于评估 AI 结果模块对自然结果可见区域的挤压程度。

提交 Google AI Mode SERP 任务 ​

接口概述 ​

请求地址 ​

计费与调用限制 ​

请求格式 ​

结果获取方式 ​

主要参数 ​

附加参数 ​

返回结果说明 ​

顶层字段 ​

tasks 数组字段 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应示例 ​

常见状态与错误说明 ​

使用建议 ​

实用场景 ​