AI 优化响应

本平台支持面向大语言模型（LLM）和 AI 应用优化的 API 响应格式。

在接口 URL 末尾追加 .ai 后缀后，返回结果将变为裁剪版 JSON，便于模型消费、减少无效字段并降低上下文占用。

功能说明

AI 优化响应与普通响应相比，主要有以下差异：

• 服务层字段精简为 3 个：
• id
• status_code
• status_message
• items 数组中不会返回值为空、null 或 false 的字段
• float 类型数值会四舍五到小数点后 3 位
• 移除 position 和 xpath 字段
• monthly_searches 对象会以更紧凑的键值结构返回，例如：

{
"2025-03": 201000,
"2025-04": 201000
}

• 对于支持任务设置参数的接口，若 depth 和/或 limit 参数，默认值会设为 10
• 地理位置类接口在默认 URL（例如 /locations.ai）下返回国家级数据；若需要获取某个国家下的城市数据，请在路径中追加国家代码，例如：
• locations/US.ai

支持范围

AI 优化响应适用于：

• 所有 Live 接口
• 所有 Task GET 接口

，最适合使用该能力的接口通常：

• /v3/serp/ 接口
• /v3/dataforseo_labs/ 接口

计费说明

使用 .ai 响应格式不会产生额外费用。

仍按对应接口的正常调用价格计费，扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求格式

POST 请求

POST https://api.seermartech.cn/v3/$path.ai

GET 请求

GET https://api.seermartech.cn/v3/$path/$id.ai

动态路径参数

参数	类型	说明
path	string	接口路径，例如 serp/google/organic/live/regular
id	string	任务唯一标识，用于 Task GET 接口，例如 05281810-1535-0121-0000-014aadae6b3a

AI 优化响应结构

返回结果为 JSON 编码数据每个任务结果以下核心字段：

字段名	类型	说明
id	string	任务唯一标识，UUID 格式
status_code	integer	通用状态码。建议在接时建立完整的异常与错误处理机制
status_message	string	通用状态说明信息
items	array	与当前任务的数据结果数组

完整响应码及含义请参考错误码文档。

请求示例

以下示例展示如何获取 Google Organic Live Regular 的 AI 优化响应。

cURL

curl --location --request POST "https://api.seermartech.cn/v3/serp/google/organic/live/regular.ai" \
 --header "Authorization: Bearer smt_live_YOUR_KEY" \
 --header "Content-Type: application/json" \
 --data-raw '[
 {
 "language_code": "en",
 "location_code": 2840,
 "keyword": "albert einstein"
 }
 ]'

Python

import requests

url = "https://api.seermartech.cn/v3/serp/google/organic/live/regular.ai"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}
data = [
 {
 "language_code": "en",
 "location_code": 2840,
 "keyword": "albert einstein"
 }
]

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

TypeScript

import axios from "axios";

async function main {
 const response = await axios.post(
 "https://api.seermartech.cn/v3/serp/google/organic/live/regular.ai",
 [
 {
 language_code: "en",
 location_code: 2840,
 keyword: "albert einstein",
 },
 ],
 {
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json",
 },
 }
 );

 // 返回 AI 优化后的响应结构
 console.log(response.data);
}

main.catch(console.error);

响应示例

以下为 Google Organic Regular SERP 的 AI 优化响应示例：

{
 "id": "05281810-1535-0121-0000-014aadae6b3a",
 "status_code": 20000,
 "status_message": "Ok.",
 "items": []
}

使用建议

当你需要将接口结果直接提供给以下场景时，建议优使用 .ai 后缀：

• LLM 自动摘要
• AI Agent 调用搜索结果
• RAG 数据预处理
• 减少响应体积与无效字段
• 降低提示词上下文消耗

状态码说明

status_code 和 status_message 为通用响应状态字段。 请在系统中至少处理以下：

• 请求成功
• 参数错误
• 认证失败
• 任务不存在 -额或余额不足
• 平台处理异常

错误码与含义请参考错误码文档。

注意事项

• .ai 改变响应结构，不改变接口核心能力
• 对于 Task GET 接口，仍需使用任务 id 获取结果，只是路径后缀改为 .ai
• 对于位置类接口，如需更细粒度数据，需要在路径中明确指定国家代码
• 若业务依赖 position、xpath、空字段或完整精度浮点数，请继续使用标准响应而非 .ai

实用场景

• 裁剪 SERP 结果供大模型消费：将搜索结果直接问答机器人或助手，减少无效字段，降低上下文占用和推理成本。
• 构建轻量级 SEO Agent：让智能体直接调用 /v3/serp/ 或 /v3/dataforseo_labs/ 接口，使用更短的 JSON 快速完成抓取、解析与决策。
• 整理月度搜索趋势：利用更紧凑的 monthly_searches 返回结构，便于生成趋势摘要、波动判断和报表描述。
• 降低数据洗工作量：自动去除 null、空值和 false 字段，减少应用层洗逻辑，加快数据库或向量化处理。
• 优化多轮分析链路：在 LLM + 工作流场景中缩短单次响应体积，提高链路稳定性，因返回过长导致上下文限。