AI 优化：LLM 提及搜索（实时，容路径）

> 接口契约： POST /v3/ai_optimization/llm_mentions/search/live

接口说明

本接口用于实时获取 AI 搜索中的品牌、域名或提及信息，以及搜索指标。返回结果取决于以下条件：

目标平台：google（Google AI Overview）或 chat_gpt（ChatGPT）
搜索地区
搜索语言
目标实体及筛选条件

路径容说明

当前路径为容路径：

text

/v3/ai_optimization/llm_mentions/search/live

平台已提供新的推荐路径：

text

/v3/ai_optimization/llm_mentions/search_mentions/live

当前容路径暂未设置停用日期，但新接项目建议使用新路径。本文档保留对旧路径的说明，以确保现有集成正常运行。

请求限制

请求方法：POST
请求体格式：JSON 数组，使用 UTF-8 编码
每次请求最多 1 个任务
target 最多 10 个目标实体
接口处理时间最长约为 120 秒平台限流以认证说明中的 30/60/120 次/分钟规则为准

计费

本接口按任务计费。费用取决于请求参数及返回数据量。

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

请求参数

请求体是数组，每个数组代表一个任务。

任务级参数

参数	类型	填	说明
`target`	array	是	目标实体数组，最多 10 个对象。每个对象只能一个 `domain` 或一个 `keyword`
`location_name`	string	否	搜索地区名称。指定后无需再传 `location_code`
`location_code`	integer	否	搜索地区代码。默认值为 `2840`
`language_name`	string	否	搜索语言名称。指定后无需再传 `language_code`
`language_code`	string	否	搜索语言代码。默认值为 `en`
`platform`	string	否	AI 搜索平台，可选 `google`、`chat_gpt`，默认值为 `google`
`filters`	array	否	结果过滤条件，最多 8 个过滤条件
`order_by`	array	否	结果排序规则，最多 3 条
`offset`	integer	否	结果偏移量，默认值为 `0`，最大值为 `9000`
`search_after_token`	string	否	分页令牌，用于获取后续结果。使用时，请求参数与上一次请求保持一致
`limit`	integer	否	最大返回对象数，默认值为 `100`，最大值为 `1000`
`tag`	string	否	自定义任务标识，最长 255 个字符。该值会原样返回在响应的 `data` 对象中

地区与语言限制

可以通过以下接口获取可用的地区和语言列表：

text

GET /v3/ai_optimization/llm_mentions/locations_and_languages

平台限制如下：

平台	可用地区	可用语言
`google`	取决于地区列表	取决于语言列表
`chat_gpt`	支持 United States，代码 `2840`	支持 English，代码 `en`

如果未指定地区，将使用 location_code: 2840。如果未指定语言，将使用 language_code: en。

`target` 参数

target 是目标实体数组。一个目标实体可以是域名实体或实体。

域名实体

域名实体用于查找 AI 回答或搜索结果中是否提及指定域名。

json

{
  "domain": "example.com",
  "search_filter": "exclude",
  "search_scope": ["sources"],
  "include_subdomains": true
}

参数	类型	填	说明
`domain`	string	条件填	目标域名。不应 `https://` 或 `www.`，最长 63 个字符
`search_filter`	string	否	域名筛选方式：`include`、`exclude`。默认值为 `include`
`search_scope`	array	否	搜索范围：`any`、`sources`、`search_results`。默认值为 `any`
`include_subdomains`	boolean	否	是否目标域名的子域名。默认值为 `false`

：

include：匹目标域名的结果
exclude：排除匹目标域名的结果
any：搜索可用范围
sources：搜索 AI 回答引用的来源
search_results：搜索模型检索到的搜索结果

实体

实体用于查找 AI 搜索中的问题、回答、品牌实体或扩展查询。

json

{
  "keyword": "bmw",
  "search_filter": "include",
  "search_scope": ["answer"],
  "match_type": "partial_match"
}

参数	类型	填	说明
`keyword`	string	条件填	目标，最长 250 个字符
`search_filter`	string	否	筛选方式：`include`、`exclude`。默认值为 `include`
`search_scope`	array	否	搜索范围：`any`、`question`、`answer`、`brand_entities`、`fan_out_queries`。默认值为 `any`
`match_type`	string	否	匹方式：`word_match`、`partial_match`。默认值为 `word_match`

编码规则

中的 URL 编码字符会被解码，字符 + 会被解码为空格。

如果本身以下字符，应进行二次编码：

% 请写为 %25
+ 请写为 %2B

`match_type` 取值

word_match：词匹。例如搜索 light，可匹 light bulb、light switch。
partial_match：子字符串匹。例如搜索 light，可匹 lighting、highlight。

过滤与排序

`filters`

filters 用于筛选返回结果。多个条件之间指定逻辑 and 或 or。

支持的运算符：

text

=       等于
<>      不等于
in      属于
not_in  不属于
like    模糊匹
not_like 不匹
ilike   不区分大小写的模糊匹
not_ilike 不区分大小写的不匹
match   匹
not_match 不匹

like 和 not_like 支持使用 % 匹任意长度的字符串。

示例：

json

"filters": [
  ["ai_search_volume", ">", 1000]
]

完整过滤字段列表请参考：

text

/v3/ai_optimization/llm_mentions/filters/

`order_by`

order_by 使用与 filters 相同的字段，并通过逗号指定排序方向：

json

"order_by": [
  "ai_search_volume,desc"
]

排序方向：

asc：升序
desc：降序

单次请求最多设置 3 条排序规则。

分页参数

`offset`

offset 表示跳过的结果数量。例如：

json

"offset": 10

表示跳过前 10 个提及对象，从后续结果开始返回。

最大值为 9000。如果需要获取更多结果，应改用 search_after_token。

`search_after_token`

响应中会返回 search_after_token。将该值放下一次请求，可以获取同一任务的后续结果。

使用该参数时：

-须使用上一次响应返回的令牌

请求参数保持一致
每个后续任务的令牌均唯一性
适合获取 20,000 条结果，请求时

请求示例

cURL

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/ai_optimization/llm_mentions/search/live" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "language_name": "English",
      "location_code": 2840,
      "target": [
        {
          "domain": "example.com",
          "search_filter": "exclude"
        },
        {
          "keyword": "bmw",
          "search_scope": ["answer"]
        }
      ],
      "platform": "google",
      "filters": [
        ["ai_search_volume", ">", 1000]
      ],
      "order_by": [
        "ai_search_volume,desc"
      ],
      "offset": 0,
      "limit": 3,
      "tag": "brand-monitoring-demo"
    }
  ]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/ai_optimization/llm_mentions/search/live"

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

payload = [
    {
        "language_name": "English",
        "location_code": 2840,
        "target": [
            {
                "domain": "example.com",
                "search_filter": "exclude",
            },
            {
                "keyword": "bmw",
                "search_scope": ["answer"],
            },
        ],
        "platform": "google",
        "filters": [
            ["ai_search_volume", ">", 1000],
        ],
        "order_by": [
            "ai_search_volume,desc",
        ],
        "limit": 3,
    }
]

response = requests.post(url, headers=headers, json=payload, timeout=150)
response.raise_for_status()

result = response.json()
print(result)

TypeScript

typescript

import axios from "axios";

const response = await axios.post(
  "https://api.seermartech.cn/v3/ai_optimization/llm_mentions/search/live",
  [
    {
      language_name: "English",
      location_code: 2840,
      target: [
        {
          domain: "example.com",
          search_filter: "exclude",
        },
        {
          keyword: "bmw",
          search_scope: ["answer"],
        },
      ],
      platform: "google",
      filters: [["ai_search_volume", ">", 1000]],
      order_by: ["ai_search_volume,desc"],
      limit: 3,
    },
  ],
  {
    headers: {
      Authorization: "Bearer smt_live_YOUR_KEY",
      "Content-Type": "application/json",
    },
    timeout: 150000,
  }
);

console.log(response.data);

响应结构

接口返回 JSON 对象 tasks 数组。

顶层响应字段

字段	类型	说明
`version`	string	当前 API 版本
`status_code`	integer	请求级状态码。`20000` 表示成功
`status_message`	string	请求级状态信息
`time`	string	请求执行时间，单位为秒
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`tasks_count`	integer	`tasks` 数组中的任务数量
`tasks_error`	integer	执行失败的任务数量
`tasks`	array	任务结果数组

任务字段

字段	类型	说明
`id`	string	任务唯一标识，UUID 格式
`status_code`	integer	任务状态码，通常位于 `10000` 至 `60000` 范围
`status_message`	string	任务状态信息
`time`	string	任务执行时间
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`result_count`	integer	`result` 数组中的数量
`path`	array	请求路径信息
`data`	object	本次 POST 请求中提交的参数
`result`	array	搜索结果数组

`result` 字段

字段	类型	说明
`total_count`	integer	符合请求条件的结果总数
`current_offset`	integer	当前已跳过的结果数量
`search_after_token`	string	获取后续结果时使用的分页令牌
`items_count`	integer	`items` 数组中的结果数量
`items`	array	LLM 提及及指标数据

`items` 字段

字段	类型	说明
`platform`	string	请求中指定的平台
`model_name`	string	生成数据的 AI 模型名称。`google` 平台通常返回 `google_ai_overview`
`location_code`	integer	请求中的地区代码
`language_code`	string	请求中的语言代码
`question`	string	问题或用户查询
`answer`	string	AI 返回的回答，使用 Markdown 格式
`sources`	array	AI 最终回答引用或依赖的来源
`search_results`	array/null	模型检索到的网页搜索结果，可能重复或未被最终回答使用的结果
`ai_search_volume`	integer	当前的 AI 搜索量
`monthly_searches`	array	按月份统计的 AI 搜索量
`first_response_at`	string	首次记录该回答的时间，UTC 格式
`last_response_at`	string	最近更新该回答的时间，UTC 格式
`brand_entities`	array/null	回答中识别出的品牌实体
`fan_out_queries`	array/null	从主查询扩展出的查询

`sources` 来源字段

sources 表示模型在最终回答中引用或依赖的来源。

字段	类型	说明
`snippet`	string	来源摘要或描述
`source_name`	string	来源名称
`thumbnail`	string/null	来源缩略图
`markdown`	string/null	Markdown 格式的来源
`position`	integer	来源在结果中的位置
`title`	string	来源标题
`domain`	string	来源域名
`url`	string	来源 URL
`publication_date`	string/null	发布时间

publication_date 示例：

text

2019-11-15 12:57:46 +00:00

`search_results` 搜索结果字段

字段	类型	说明
`description`	string	搜索结果描述
`breadcrumb`	string	页面面屑
`position`	integer	搜索结果位置
`title`	string	搜索结果标题
`domain`	string	结果域名
`url`	string	结果 URL
`publication_date`	string/null	发布时间

`monthly_searches` 月度搜索量字段

字段	类型	说明
`year`	integer	年份
`month`	integer	月份
`search_volume`	integer	对应月份的 AI 搜索量

示例：

json

"monthly_searches": [
  {
    "year": 2025,
    "month": 11,
    "search_volume": 1500000
  }
]

`brand_entities` 品牌实体字段

字段	类型	说明
`position`	integer	品牌在结果中的位置
`title`	string	品牌名称
`category`	string	品牌所属类别

`fan_out_queries` 扩展查询

fan_out_queries 是模型根据主查询自动生成的搜索查询，用于扩大检索范围并生成更完整的回答。

响应示例

以下为精简示例，响应中的 sources、search_results 和 items 数量取决于查询条件及 limit 参数。

json

{
  "version": "0.1.20251208",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.5640 sec.",
  "cost": 0.103,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "019b0000-0000-7000-8000-000000000001",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.5640 sec.",
      "cost": 0.103,
      "result_count": 1,
      "path": [
        "v3",
        "ai_optimization",
        "llm_mentions",
        "search",
        "live"
      ],
      "data": {
        "api": "ai_optimization",
        "function": "search",
        "language_name": "English",
        "location_code": 2840,
        "platform": "google",
        "limit": 3
      },
      "result": [
        {
          "total_count": 1,
          "current_offset": 0,
          "search_after_token": "eyJvZmZzZXQiOjF9",
          "items_count": 1,
          "items": [
            {
              "platform": "google",
              "model_name": "google_ai_overview",
              "location_code": 2840,
              "language_code": "en",
              "question": "bmw",
              "answer": "BMW 是一家德国汽车和摩托车制造商。",
              "sources": [
                {
                  "snippet": "来源摘要",
                  "source_name": "示例来源",
                  "thumbnail": null,
                  "markdown": null,
                  "position": 1,
                  "title": "示例标题",
                  "domain": "example.com",
                  "url": "https://example.com/page",
                  "publication_date": null
                }
              ],
              "search_results": null,
              "ai_search_volume": 1500000,
              "monthly_searches": [
                {
                  "year": 2025,
                  "month": 11,
                  "search_volume": 1500000
                }
              ],
              "first_response_at": "2025-11-09 02:05:50 +00:00",
              "last_response_at": "2025-11-09 02:05:50 +00:00",
              "brand_entities": null,
              "fan_out_queries": null
            }
          ]
        }
      ]
    }
  ]
}

状态码与错误处理

建议客户端同时检查：

顶层 status_code
任务级 status_code
status_message
tasks_error

当 status_code 不等于 20000 时，应记录错误信息并根据业务需要执行重试、降级或告警。完整错误码请参考本平台错误码文档。

实用场景

监测品牌在 AI 回答中的提及：统计品牌被 AI 搜索引用、描述和推荐的频率，评估品牌在生成式搜索中的可见度。
分析竞争对手的 AI 搜索表现：同时提交多个品牌域名或，对比不同品牌的提及量、引用来源和回答位置。
定位品牌引用来源缺口：筛选 sources 和 search_results，发现 AI 搜索频繁引用但尚未覆盖的媒体、百科或行业网站。
跟踪高 AI 搜索量：使用 ai_search_volume 过滤和排序，优识别较高生成式搜索需求的。
研究 AI 回答的查询扩展路径：分析 fan_out_queries，挖掘用户问题的意图，为集群和 SEO 选题提供依据。

AI 优化：LLM 提及搜索（实时，容路径） ​

接口说明 ​

路径容说明 ​

请求限制 ​

计费 ​

请求参数 ​

任务级参数 ​

地区与语言限制 ​

target 参数 ​

域名实体 ​

实体 ​

编码规则 ​

match_type 取值 ​

过滤与排序 ​

filters ​

order_by ​

分页参数 ​

offset ​

search_after_token ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应结构 ​

顶层响应字段 ​

任务字段 ​

result 字段 ​

items 字段 ​

sources 来源字段 ​

search_results 搜索结果字段 ​

monthly_searches 月度搜索量字段 ​

AI 优化：LLM 提及搜索（实时，容路径）

接口说明

路径容说明

请求限制

计费

请求参数

任务级参数

地区与语言限制

`target` 参数

域名实体

实体

编码规则

`match_type` 取值

过滤与排序

`filters`

`order_by`

分页参数

`offset`

`search_after_token`

请求示例

cURL

Python

TypeScript

响应结构

顶层响应字段

任务字段

`result` 字段

`items` 字段

`sources` 来源字段

`search_results` 搜索结果字段

`monthly_searches` 月度搜索量字段