主题
LLM 提及品牌排行（实时）
POST /v3/ai_optimization/llm_mentions/top_mentioned_brands/live
本接口通过大语言模型（LLM）提及数据，按指定目标的品牌提及频次聚合并返回品牌排行。结果受平台、地区和语言参数影响。
请求方式与路径：
POST /v3/ai_optimization/llm_mentions/top_mentioned_brands/live
品牌实体数据目前支持 chat_gpt 平台。
接口说明
- 请求体使用 UTF-8 编码的 JSON 数组。
- 每次请求只能提交 1 个任务。
target最多 10 个目标实体。 平台限流以认证说明中的 30/60/120 次/分钟规则为准。- 实时任务执行时间最长约为 120 秒。
- 任务提交成功后，接口会直接返回任务结果。
- 实扣费以响应头
X-SeerMarTech-Charge-CNY为准。
请求参数
顶层参数
| 参数 | 类型 | 填 | 说明 |
|---|---|---|---|
target | array | 是 | 目标实体数组，最多 10 个实体。每个实体 domain 或 keyword 之一。 |
location_name | string | 否 | 搜索地区名。使用该参数时无需传 location_code。默认地区代码为 2840。 |
location_code | integer | 否 | 搜索地区代码。使用该参数时无需传 location_name。默认值为 2840。 |
language_name | string | 否 | 搜索语言名。使用该参数时无需传 language_code。默认语言代码为 en。 |
language_code | string | 否 | 搜索语言代码。使用该参数时无需传 language_name。默认值为 en。 |
platform | string | 否 | 目标平台，可选：chat_gpt、google。 |
filters | array | 否 | 在聚合结果上执行过滤。最多设置 8 个过滤条件。 |
initial_dataset_filters | array | 否 | 在聚合前对原始提及数据进行过滤，限制参与统计的数据行。最多设置 8 个过滤条件。 |
limit | integer | 否 | items 数组的最大结果数量，范围 1-1000，默认值为 100。 |
internal_list_limit | integer | 否 | 部数组的最大数量，适用于 sources_domain、search_results_domain、brand_entities_title 和 brand_entities_category。范围 1-10，默认值为 5。 |
order_by | array | 否 | 结果排序规则，最多设置 3 条。 |
offset | integer | 否 | 结果偏移量，默认值为 0，最大值为 1000000。 |
include_brands | array | 否 | 返回指定品牌。 |
exclude_brands | array | 否 | 排除指定品牌。 |
tag | string | 否 | 自定义任务标识，最长 255 个字符。该值会原样返回在响应任务的 data 对象中。 |
地区与语言限制
当 platform 为 chat_gpt 时：
location_name支持United States。location_code支持2840。language_name支持English。language_code支持en。
可通过以下容路径获取可用地区和语言：
/v3/ai_optimization/llm_mentions/locations_and_languages
target 参数
target 是由目标实体对象组成的数组。每个对象只能指定一个 domain 或一个 keyword。
至少需要一个 search_filter 为 include 的 domain 实体或 keyword 实体。
域名实体
| 参数 | 类型 | 填 | 说明 |
|---|---|---|---|
domain | string | 条件填 | 目标域名。未指定 keyword 时填，最长 63 个字符。不要 https:// 或 www.。 |
search_filter | string | 否 | 域名过滤方式：include、exclude。默认值为 include。 |
search_scope | array | 否 | 域名搜索范围：any、sources、search_results。默认值为 any。 |
include_subdomains | boolean | 否 | 是否目标域名的子域名。默认值为 false。 |
示例：
json
{
"domain": "example.com",
"search_filter": "include",
"search_scope": ["any"],
"include_subdomains": true
}实体
| 参数 | 类型 | 填 | 说明 |
|---|---|---|---|
keyword | string | 条件填 | 目标。未指定 domain 时填，最长 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。 |
match_type 说明：
word_match：执行匹，可匹目标词前后或词组词的。partial_match：匹中出现的或片段。
示例：
json
{
"keyword": "electric vehicles",
"search_filter": "include",
"search_scope": ["question", "answer"],
"match_type": "partial_match"
}过滤器
filters 用于对聚合后的结果进行过滤；initial_dataset_filters 用于聚合前过滤原始提及数据。
两均支持以下运算符：
=、<>、in、not_in、like、not_like、ilike、not_ilike、match、not_match
使用 like 或 not_like 时，可以使用 % 匹任意长度的字符串。多个条件之间需要通过逻辑运算符 and 或 or 连接。
示例：
json
[
["ai_search_volume", ">", 10],
"and",
["mentions", ">=", 5]
]排序
order_by 使用与过滤器相同的字段和排序表达式，排序方向为：
asc：升序desc：降序
多个排序规则之间使用逗号分隔，最多设置 3 条。
示例：
json
[
"total.mentions,desc",
"brand,asc"
]请求示例
curl
bash
curl --location --request POST \
"https://api.seermartech.cn/v3/ai_optimization/llm_mentions/top_mentioned_brands/live" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
{
"language_code": "en",
"location_code": 2840,
"platform": "chat_gpt",
"target": [
{
"keyword": "bmw",
"search_scope": ["answer"]
},
{
"keyword": "auto",
"search_scope": ["question"],
"match_type": "partial_match"
}
],
"initial_dataset_filters": [
["ai_search_volume", ">", 10]
],
"limit": 5,
"internal_list_limit": 2
}
]'Python
python
import requests
url = "https://api.seermartech.cn/v3/ai_optimization/llm_mentions/top_mentioned_brands/live"
headers = {
"Authorization": "Bearer smt_live_YOUR_KEY",
"Content-Type": "application/json",
}
payload = [
{
"language_code": "en",
"location_code": 2840,
"platform": "chat_gpt",
"target": [
{
"keyword": "bmw",
"search_scope": ["answer"],
},
{
"keyword": "auto",
"search_scope": ["question"],
"match_type": "partial_match",
},
],
"initial_dataset_filters": [
["ai_search_volume", ">", 10],
],
"limit": 5,
"internal_list_limit": 2,
}
]
response = requests.post(url, headers=headers, json=payload, timeout=130)
response.raise_for_status()
result = response.json()
print(result)TypeScript
typescript
import axios from "axios";
const url =
"https://api.seermartech.cn/v3/ai_optimization/llm_mentions/top_mentioned_brands/live";
const payload = [
{
language_code: "en",
location_code: 2840,
platform: "chat_gpt",
target: [
{
keyword: "bmw",
search_scope: ["answer"],
},
{
keyword: "auto",
search_scope: ["question"],
match_type: "partial_match",
},
],
initial_dataset_filters: [["ai_search_volume", ">", 10]],
limit: 5,
internal_list_limit: 2,
},
];
const response = await axios.post(url, payload, {
headers: {
Authorization: "Bearer smt_live_YOUR_KEY",
"Content-Type": "application/json",
},
timeout: 130000,
});
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 | 任务结果数组。 |
tasks素字段
| 字段 | 类型 | 说明 |
|---|---|---|
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 | 本次请求中提交的参数。 |
result | array | 任务结果数组。 |
结果字段
result 数组中的结果对象以下字段：
| 字段 | 类型 | 说明 |
|---|---|---|
total_count | integer | 与请求条件匹的结果总数。 |
offset | integer | 已跳过的结果数量。 |
items_count | integer | 当前 items 数组返回的结果数量。 |
aggregated_metrics | object | 所有匹品牌的聚合提及指标。 |
items | array | 按品牌拆分的详细结果。 |
aggregated_metrics
该对象跨品牌、地区、语言、平台及来源维度的聚合数据。
| 字段 | 类型 | 说明 |
|---|---|---|
location | array | 按地区聚合的指标。 |
language | array | 按语言聚合的指标。 |
platform | array | 按 AI 平台聚合的指标。 |
sources_domain | array | 与目标、被 LLM 回答引用的主要来源域名。 |
search_results_domain | array | 与 LLM 查询、出现在搜索结果中的主要域名。 |
brand_entities_title | array | 品牌实体标题。 |
brand_entities_category | array | 品牌实体类别。 |
total | object | 所有维度的总体聚合指标。 |
除 location.key 为整数外，上述分组数组中的每个通常：
| 字段 | 类型 | 说明 |
|---|---|---|
key | string / integer | 分组标识。对于域名维度，该值为域名；对于语言、平台或品牌维度，该值为对应名称或标识。 |
mentions | integer | 目标或域名在该分组中的 LLM 提及次数。 |
ai_search_volume | integer | 该分组提及数据对应的聚合 AI 搜索量。 |
total 对象字段：
| 字段 | 类型 | 说明 |
|---|---|---|
mentions | integer | 与目标的 LLM 提及总次数。 |
ai_search_volume | integer | 所有提及的总 AI 搜索量。 |
items
items 数组中的每个代表一个被提及的品牌。
| 字段 | 类型 | 说明 |
|---|---|---|
brand | string | 品牌名称。 |
location | array | 该品牌按地区拆分的提及指标。 |
language | array | 该品牌按语言拆分的提及指标。 |
platform | array | 该品牌按 AI 平台拆分的提及指标。 |
sources_domain | array | 与该品牌、被 LLM 回答引用的来源域名。 |
search_results_domain | array | 与该品牌、出现在 LLM 查询搜索结果中的域名。 |
brand_entities_title | array | 与该品牌的品牌实体标题。 |
brand_entities_category | array | 与该品牌的品牌实体类别。 |
total | object | 该品牌的提及指标汇总。 |
items 中各分组数组的结构与 aggregated_metrics 中对应数组一致：
json
{
"key": "example.com",
"mentions": 120,
"ai_search_volume": 2400
}items[].total 字段：
| 字段 | 类型 | 说明 |
|---|---|---|
mentions | integer | 与该品牌的 LLM 提及总次数。 |
ai_search_volume | integer | 与该品牌提及的总 AI 搜索量。 |
响应示例
json
{
"version": "0.1.20251208",
"status_code": 20000,
"status_message": "Ok.",
"time": "1.9150 sec.",
"cost": 0.101,
"tasks_count": 1,
"tasks_error": 0,
"tasks": [
{
"id": "00000000-0000-0000-0000-000000000000",
"status_code": 20000,
"status_message": "Ok.",
"time": "1.8000 sec.",
"cost": 0.101,
"result_count": 1,
"path": [
"v3",
"ai_optimization",
"llm_mentions",
"top_mentioned_brands",
"live"
],
"data": {
"language_code": "en",
"location_code": 2840,
"platform": "chat_gpt",
"target": [
{
"keyword": "bmw",
"search_scope": ["answer"]
},
{
"keyword": "auto",
"search_scope": ["question"],
"match_type": "partial_match"
}
],
"initial_dataset_filters": [
["ai_search_volume", ">", 10]
],
"limit": 5,
"internal_list_limit": 2
},
"result": [
{
"total_count": 5,
"offset": 0,
"items_count": 5,
"aggregated_metrics": {
"location": [
{
"key": 2840,
"mentions": 9999,
"ai_search_volume": 99999
}
],
"language": [
{
"key": "en",
"mentions": 9999,
"ai_search_volume": 99999
}
],
"platform": [
{
"key": "chat_gpt",
"mentions": 9999,
"ai_search_volume": 99999
}
],
"sources_domain": [],
"search_results_domain": [],
"brand_entities_title": [],
"brand_entities_category": [],
"total": {
"mentions": 9999,
"ai_search_volume": 99999
}
},
"items": [
{
"brand": "Toyota",
"location": [],
"language": [],
"platform": [],
"sources_domain": [],
"search_results_domain": [],
"brand_entities_title": [],
"brand_entities_category": [],
"total": {
"mentions": 600,
"ai_search_volume": 6000
}
}
]
}
]
}
]
}实用场景
- 对比目标下的品牌提及排名，识别竞争品牌在 LLM 回答中的可见度差异，优化品牌与 SEO 投放策略。
- 筛选
sources_domain和search_results_domain，定位影响 LLM 引用和搜索结果的高价值网站，制定外链和合作计划。 - 按地区、语言和平台拆分品牌提及数据，发现不同市场中的 AI 搜索差异，支持化 SEO 和本地调整。
- 使用
initial_dataset_filters聚合高 AI 搜索量提及数据，优分析高需求查询，提升品牌监测和资源分效率。 - 通过
include_brands或exclude_brands聚焦指定品牌集合，构建竞品追踪报表并持续监控品牌声量变化。