设置 Google AI Mode SERP 任务

POST /v3/serp/google/ai_mode/task_post

本接口使用 POST 方法，通过 /v3/serp/google/ai_mode/task_post 提交 Google AI Mode 搜索结果采集任务。

Google AI Mode SERP API 用于获取 Google Search AI Mode 功能返回的搜索结果。任务支持两种执行优级：

1：普通优级，默认值
2：高优级，执行速度更快，但会产生额外费用

接口在成功创建任务时计费。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求地址

text

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

请求说明

请求体使用 UTF-8 编码的 JSON 格式。
请求体是 JSON 数组，所有任务参数都放在数组中。
单次请求最多提交 100 个任务。平台限流以认证说明中的 30/60/120 次/分钟规则为准。
如果单次请求 100 个任务，出部分将返回错误码 40006。
创建任务后，可以通过返回的任务 ID 获取结果。
也可以在请求中 pingback_url 或 postback_url，任务完成后由本平台主动通知。

如果回调服务器在 10 秒未返回响应，连接将因时中断，任务会转移到任务就绪列表。建议为回调接口设计完善的时、重试和异常处理机制。

请求参数

核心参数

参数	类型	填	说明
`keyword`	string	是	查询，最长 700 个字符。传值中的 `%XX` 编码会被解码，字符 `+` 会被解码为空格。如果中需要使用 `%`，请传 `%25`；如果需要使用 `+`，请传 `%2B`。
`location_code`	integer	条件填	搜索位置代码。当未指定 `location_name` 或 `location_coordinate` 时填。指定该参数后，无需再传 `location_name` 或 `location_coordinate`。可通过 `/v3/serp/google/locations` 获取可用位置及代码。AI Mode 当前在部分国家或地区可用，请以 Google Search 的支持范围为准。
`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` 和 `$tag` 占位符，发送时会替换为任务 ID 和经过 URL 编码的标签值。特殊字符会进行 URL 编码，例如 `#` 会编码为 `%23`。
`postback_url`	string	否	任务完成后的结果接收地址。本平台将以 POST 方式向该地址发送结果，使用 `gzip` 压缩。支持使用 `$id` 和 `$tag` 占位符，发送时会替换为值。特殊字符会进行 URL 编码。
`postback_data`	string	条件填	`postback_url` 的数据格式。当指定 `postback_url` 时填。可选值：`advanced`、`html`。

附加参数

参数	类型	填	说明
`location_name`	string	条件填	搜索位置的完整名称。当未指定 `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素的像素排名适用于 `advanced` 结果。像素排名表示结果摘要到屏幕左上角的距离。默认值为 `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`	number	否	浏览器屏幕分辨率比例，用于计算指定设备下的像素排名。取值范围为 `0.5-3`。默认值：桌面端 `1`；Android 移动端 `3`；iOS 移动端 `3`。使用该参数时将 `calculate_rectangles` 设置为 `true`。
`location_coordinate`	string	条件填	位置的 GPS 坐标，格式为 `"纬度,经度,缩放级别"`。例如：`52.6178549,-155.352142,18z`。如果未指定缩放级别，默认使用 `9z`；纬度和经度最多支持 7 位小数；缩放级别范围为 `4z-18z`。指定后，无需再传 `location_code` 或 `location_name`。

location_code、location_name 和 location_coordinate 三只能选择一。

language_code 和 language_name 二只能选择一。

请求示例

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 数组，单次最多 100 个任务
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, timeout=30)
result = response.json()

if result.get("status_code") == 20000:
    print(result)
else:
    print(
        f"请求失败，错误码：{result.get('status_code')}，"
        f"消息：{result.get('status_message')}"
    )

TypeScript

typescript

import axios from "axios";

const tasks = [
  {
    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
  .post(
    "https://api.seermartech.cn/v3/serp/google/ai_mode/task_post",
    tasks,
    {
      headers: {
        Authorization: "Bearer smt_live_YOUR_KEY",
        "Content-Type": "application/json",
      },
    }
  )
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.error(error.response?.data || error.message);
  });

响应参数

接口返回 JSON 数据已创建任务的信息。

字段	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	请求级状态码。完整错误码列表请参考错误码文档。
`status_message`	string	请求级状态说明。
`time`	string	请求执行耗时，单位为秒。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`tasks_count`	integer	`tasks` 数组中的任务总数。
`tasks_error`	integer	`tasks` 数组中返回错误的任务数量。
`tasks`	array	已提交任务的数组。

`tasks` 数组字段

字段	类型	说明
`id`	string	任务唯一标识，UUID 格式。后续可使用该 ID 获取任务结果。
`status_code`	integer	任务状态码，取值范围通常为 `10000-60000`。
`status_message`	string	任务状态说明。
`time`	string	任务执行耗时，单位为秒。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`result_count`	integer	`result` 数组中的结果数量。创建任务时通常为 `0`。
`path`	array	任务对应的 URL 路径信息。
`data`	object	创建任务时提交的参数。
`result`	array \| null	任务结果数组。任务创建接口返回时为 `null`。

响应示例

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": "some-uuid-task-id",
      "status_code": 20100,
      "status_message": "Task Created.",
      "time": "0.0123 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
    }
  ]
}

错误处理

当顶层 status_code 不为 20000 时，表示本次请求未成功完成。
当 tasks_error 大于 0 时，表示部分任务提交失败，应逐项检查 tasks 数组中的任务状态。
单次提交 100 个任务时，出限制的任务会返回 40006。
建议同时检查 HTTP 状态码、顶层 status_code、任务级 status_code 和 status_message。
对于使用 pingback_url 或 postback_url 的场景，应确保回调服务器在 10 秒返回成功响应。

实用场景

监测不同国家和语言下的 Google AI Mode 搜索结果，评估在生成式搜索中的可见性。
对比桌面端与移动端的 AI Mode 结果差异，定位设备适和搜索体验问题。
批量采集目标的 AI Mode SERP 数据，为竞品分析和选题规划提供依据。
****高优级任务和回调通知，缩短实时 SEO 监控系统的结果时间。
计算SERP素的像素排名，分析摘要或结果模块在页面首屏中的位置。

设置 Google AI Mode SERP 任务 ​

请求地址 ​

请求说明 ​

请求参数 ​

核心参数 ​

附加参数 ​

请求示例 ​

curl ​

Python ​

TypeScript ​

响应参数 ​

tasks 数组字段 ​

响应示例 ​

错误处理 ​

实用场景 ​