提交 ChatGPT AI Mode 搜索任务

接口说明

通过本接口可创建 ChatGPT AI Mode 搜索任务，用于获取 ChatGPT 搜索结果。结果会受到所选地域与语言参数影响：

• 地域列表：/v3/serp/chatgpt/locations
• 语言列表：/v3/serp/chatgpt/ai_mode/languages

接口支持两种执行优级：

• 1：普通优级
• 2：高优级

高优级通常可更快执行，但会产生更高费用。

请求地址

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

计费说明

在创建任务时扣费。

参考价约 ¥0.0192 / 次。如使用高优级，费用会更高。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求格式与并发限制

• 请求体为 UTF-8 编码的 JSON
• POST 请求体格式为 JSON 数组：[{ ... }]
• 每分钟最多可发送 2000 次 API 调用
• 每次 POST 最多 100 个任务
• 如果单次请求 100 个任务，出部分将返回错误 40006

结果获取方式

任务提交成功后，你可以通过返回的唯一任务 ID 获取结果。也可以在创建任务时设置：

• postback_url：任务完成后，平台会将结果以 gzip 压缩的 POST 请求推送到该地址
• pingback_url：任务完成后，平台会向该地址发送 GET 通知

如果你的服务器在 10 秒未响应回调，请求会因时中止，任务将转移到 /v3/serp/chatgpt/ai_mode/tasks_ready/ 列表中。此时错误码与错误信息取决于你的服务器。

---

请求参数

字段名	类型	说明
keyword	string	填。搜索，最长 700 个字符。%## 会被解码，+ 会被解码为空格。如需保留 %，请写为 %25；如需保留 +，请写为 %2B。
priority	integer	可选。任务优级：1 = 普通（默认），2 = 高优级。高优级会额外收费。
location_name	string	当未提供 location_code 或 location_coordinate 时填。搜索地域完整名称。使用该字段时，无需再传 location_code 或 location_coordinate。示例：London,England,United Kingdom
location_code	integer	当未提供 location_name 或 location_coordinate 时填。搜索地域编码。使用该字段时，无需再传 location_name 或 location_coordinate。示例：2840
location_coordinate	string	当未提供 location_name 或 location_code 时填。GPS 坐标，格式为 "latitude,longitude,zoom"。若未指定 zoom，默认使用 9z。latitude 与 longitude 最多 7 位小数；zoom 最小 4z，最大 18z。示例：52.6178549,-155.352142,18z
language_name	string	当未提供 language_code 时填。搜索语言完整名称。使用该字段时，无需再传 language_code。当前支持：English
language_code	string	当未提供 language_name 时填。搜索语言编码。使用该字段时，无需再传 language_name。当前支持：en
force_web_search	boolean	可选。是否强制 AI 代理使用网页搜索。启用该参数时，web_search 也启用。开启后，模型会被要求访问并引用当前网页信息。默认值：false。注意：即使设置为 true，也不能保证结果中一定网页来源引用。
tag	string	可选。自定义任务标识，最长 255 字符。可用于结果对账与业务。该值会出现在响应的 data 对象中。
postback_url	string	可选。任务完成后，平台会向该地址发送结果的 POST 请求，结果以 gzip 格式压缩。可在 URL 中使用 $id 和 $tag 变量，系统回调时会自动替换。示例：http://your-server.com/postbackscript?id=$id、http://your-server.com/postbackscript?id=$id&tag=$tag。注意：postback_url 中的特殊字符会进行 URL 编码，例如 # 会被编码为 %23。
postback_data	string	当指定 postback_url 时填。表示回调数据类型，需与设置任务时使用的接口功能对应。可选值：advanced
pingback_url	string	可选。任务完成后，平台会向该地址发送 GET 通知。可在 URL 中使用 $id 和 $tag 变量，系统回调时会自动替换。示例：http://your-server.com/pingscript?id=$id、http://your-server.com/pingscript?id=$id&tag=$tag。注意：pingback_url 中的特殊字符会进行 URL 编码，例如 # 会被编码为 %23。

---

响应结构

接口返回 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 数组中返回错误的任务数量
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	URL 路径
data	object	回显你在请求中提交的任务参数
result	array | null	结果数组。对于 task_post 接口，此处通常为 null

---

请求示例

curl

curl --location --request POST "https://api.seermartech.cn/v3/serp/chatgpt/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 chatgpt"
 },
 {
 "language_name": "English",
 "location_name": "United States",
 "keyword": "what is chatgpt",
 "priority": 2,
 "tag": "some_string_123",
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
 }
 ]'

Python

import requests

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

# 按接口要求，POST 请求体应为 JSON 数组
payload = [
 {
 "language_code": "en",
 "location_code": 2840,
 "keyword": "what is chatgpt"
 },
 {
 "language_name": "English",
 "location_name": "United States",
 "keyword": "what is chatgpt",
 "priority": 2,
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
 }
]

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

TypeScript

import axios from "axios";

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

---

响应示例

{
 "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": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0021 sec.",
 "cost": 0.0012,
 "result_count": 0,
 "path": [
 "v3",
 "serp",
 "chatgpt",
 "ai_mode",
 "task_post"
 ],
 "data": {
 "api": "serp",
 "function": "task_post",
 "se": "chatgpt",
 "se_type": "ai_mode",
 "language_code": "en",
 "location_code": 2840,
 "keyword": "what is chatgpt",
 "device": "desktop",
 "os": "windows"
 },
 "result": null
 }
 ]
}

---

状态与错误处理说明

• 20000：请求成功
• 20100：任务已创建
• 40006：单次 POST 中的任务数量 100，出限制的任务将返回该错误

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

1. 接口级状态：检查顶层 status_code
2. 任务级状态：逐个检查 tasks[].status_code

完整错误码与说明可参考 /v3/appendix/errors。

使用建议

• 批量提交时，建议每次控制在 100 个任务
• 如需异步接收结果，可优使用 pingback_url 或 postback_url
• 若使用 postback_url，请确保服务端支持接收 gzip 压缩
• 若需要基于实时网页信息增强结果，可结合 force_web_search 使用，但不保证一定返回网页引用

实用场景

• 监控品牌词回答结果：定期提交品牌词或产品词任务，观察 ChatGPT 对品牌的回答方式与引用倾向，品牌声誉管理。
• 评估地域化搜索差异：针对不同 location_code 提交同一，比较不同国家或城市下的 AI 搜索结果差异，支持 SEO 策略制定。
• 测试提示词与问题表达：批量提交不同问法的，分析 AI 对同一主题的响应变化，优化选题与 FAQ 布局。
• 追踪热点话题可见性：对行业热点、产品问题、竞品词持续建任务，判断自身是否更容易被 AI 回答覆盖或引用。
• 构建异步采集流程：通过 pingback_url 或 postback_url 对接数据平台，实现大批量任务提交、结果回调与自动库。