快速开始

最近更新 · 2026/09/02

独角兽GEO - OpenAPI

面向接入方的对外接口文档。

第一部分：数据监测与分析API

覆盖四大数据的查询能力：品牌数据、口碑洞察、引用来源、竞品分析,并补充对话录屏与原始回复文本 查询；并开放品牌与监测计划编辑(见 5.17,仅工作区所有者可调)。

1. 基本信息

项目	说明
Base URL	`https://geo.yueyuezi.com/open-api/v1`
协议	HTTPS
鉴权	API Key(在「左下角个人中心 → API Key 管理」生成)
限流	单密钥 1 QPS,超出返回 `429 rate_limited`,响应头带 `Retry-After`
数据更新频率	天级(每日定时采集)
字符编码	UTF-8
时间格式	ISO 8601 (RFC3339);日期参数统一 `YYYY-MM-DD`

该 API Key 等价于持有人本人的账号权限,可读品牌、话题等于该账号名下完全一致的范围,请勿外泄。删除密钥后立即失效。

2. 鉴权

请求头任选一种方式传入密钥:

X-API-Key: <your-api-key>

或

Authorization: Bearer <your-api-key>

密钥本体是 32 位十六进制字符串(在「左下角个人中心 → API Key 管理」生成)。

未携带或密钥无效,返回:

{ "error": { "code": "missing_api_key", "message": "缺少 API Key..." } }
{ "error": { "code": "invalid_api_key", "message": "API Key 无效或已被删除" } }

2.1 切换工作区(可选)

如果你在多个工作区中(自己持有 + 受邀加入),默认按"自己的工作区" 访问。要查看受邀工作区下的品牌数据,请额外传:

X-Active-Workspace: <workspace_owner_public_id>

workspace_owner_public_id 是被邀请工作区所有者的 8 位数字 ID(即「个人中心」页面显示的 ID,如 12345678)。也兼容传入 UUID 格式。校验失败返回 403 workspace_forbidden。

3. 通用响应格式

成功:

{
  "data": <object | array>
}

失败:

{
  "error": {
    "code": "<machine_readable_code>",
    "message": "<human_readable_zh>"
  }
}

常见错误码:

HTTP	code	说明
401	missing_api_key	请求未带密钥
401	invalid_api_key	密钥无效或已被删除
403	workspace_forbidden	当前密钥无权访问 X-Active-Workspace 指定的工作区
400	bad_request	请求体无效或字段不合法(品牌名为空、删除品牌 name_confirm 不符等)
403	brand_forbidden	品牌不属于当前工作区,或对该资源无写权限
403	forbidden	写操作仅工作区所有者(owner)或协作者(collaborator)可执行;只读成员(member)调用时返回
404	brand_not_found	品牌不存在或已被删除
404	not_found	话题不存在或已被删除
409	entity_frozen	品牌或话题已被冻结,无法修改
422	quota_exceeded	超出套餐配额(品牌/话题数);`error.data` 带 `{resource,limit,used,plan}`
422	initial_free_topic_limit	免费版首次创建话题必须恰好创建 2 条
422	topic_type_required	品牌首个话题批次必须同时含品牌词与行业词
422	last_topic_type	删除会导致该品牌不再具备品牌词或行业词,被保护阻止
429	rate_limited	触发限流,见 `Retry-After` 头
500	internal_error	服务端异常

写操作(见 5.17)的配额类错误 quota_exceeded 会在 error 对象里额外带 data 字段:{resource,limit,used,plan}(如话题超限时 {resource:"topic",limit:3,used:3,plan:"free"}),便于接入方了解详细信息。

4. 通用查询参数

涉及时间维度的接口共享以下查询参数(具体接口的支持情况见各章节; 采集录屏按「日」查询,不使用本组参数,见 5.16):

参数	类型	默认	说明
`days`	int	7	最近 N 天(含今天);超出当前套餐上限一律 clamp 到上限
`from`	string	—	起始日期 `YYYY-MM-DD`(UTC,包含当日)
`to`	string	—	截止日期 `YYYY-MM-DD`(UTC,包含当日);`from`–`to` 跨度同样受套餐上限约束,超出会自动收紧为 `[to-(上限-1)d, to]`
`platform`	string	—	平台过滤,逗号分隔,如 `deepseek,doubao`(未传则按工作区套餐覆盖的全部平台)

查询窗口按套餐分级:免费版 7 天、基础版 180 天、专业版不限。平台数据天级更新,窗口越长 SQL 聚合开销越高,因此按套餐分级而非无限回溯。 days 与 from/to 二选一:同时传时以 from/to 为准;两者均缺省时按最近 7 天。

支持的 platform 取值:deepseek、doubao、wenxin、kimi、qianwen、yuanbao。

5. 接口列表

接口按四大数据 + 采集录屏分组。所有 :id 均为品牌 ID(UUID)。

品牌数据

5.1 品牌列表

GET /brands

返回当前工作区下的所有品牌(包含已冻结的,以 is_active=false 区分)。

示例响应

{
  "data": [
    {
      "id": "f6c5f69c-1234-4abc-9d77-2b1c0c5fdc8a",
      "name": "示例品牌",
      "website": "https://example.com",
      "description": "做云端数据库的公司",
      "is_active": true,
      "created_at": "2025-09-01T03:21:11Z",
      "updated_at": "2025-12-08T07:02:43Z"
    }
  ]
}

字段说明:

字段	类型	说明
id	string (UUID)	品牌 ID,用于其它接口的 `:id`
name	string	品牌展示名
website	string?	品牌官网,可空(空则字段缺省)
description	string?	品牌描述,可空(空则字段缺省)
is_active	bool	`false` 表示已冻结,数据停更
created_at / updated_at	string	RFC3339 时间戳

5.2 品牌详情

GET /brands/{brand_id}

返回单个品牌的基础信息(字段集合与 5.1 中的元素一致)。

5.3 话题列表

GET /brands/{brand_id}/topics

示例响应

{
  "data": [
    {
      "id": "9f4c...e1",
      "keyword": "云端数据库 推荐",
      "topic_type": "industry",
      "is_active": true,
      "monitoring_enabled": true,
      "monitoring_platforms": ["deepseek", "doubao"],
      "created_at": "2025-09-01T03:25:00Z"
    }
  ]
}

字段	说明
keyword	用户在 AI 平台模拟搜索的话题词
topic_type	`brand`(品牌词) / `industry`(行业词)
is_active	生命周期/套餐配额状态；`false` 表示话题被冻结，不等同于用户主动关闭监测
monitoring_enabled	监测计划开关；`false` 表示不进行采集
monitoring_platforms	该话题当前选择的 AI 平台范围。新增字段，旧调用方可忽略

5.4 排名概览(按话题)

GET /brands/{brand_id}/overview?days=30

返回过去 N 天该品牌每个话题的滚动统计。与平台前端「品牌数据」页分话题表的口径对齐。

示例响应

{
  "data": {
    "brand_id": "f6c5f69c-...",
    "topics": [
      {
        "topic_id": "9f4c...e1",
        "keyword": "云端数据库 推荐",
        "topic_type": "industry",
        "snapshot_count": 36,
        "platforms_covered": 6,
        "last_snapshot_date": "2025-12-08T03:48:50+08:00",
        "mention_rate_pct": 78.5,
        "first_place_rate_pct": 12.7,
        "avg_rank_score": 64.3
      }
    ]
  }
}

字段	说明
snapshot_count	窗口内该话题的快照数
platforms_covered	窗口内出现过的 AI 平台数
mention_rate_pct	我方品牌出现率(0–100)
first_place_rate_pct	排在首位的快照占比(0–100)
avg_rank_score	加权排名分(0–100,越大越好;0 表示无样本)
last_snapshot_date	窗口内最后一次采集时间(RFC3339,Shanghai 时区;窗口内无快照则为 null)

5.5 品牌整体趋势

GET /brands/{brand_id}/trend?days=30

按 (日期 × 平台) 聚合的时间序列,适合画趋势图。

示例响应

{
  "data": [
    {
      "date": "2025-12-07",
      "platform": "deepseek",
      "mention_rate_pct": 75.0,
      "first_place_rate_pct": 12.5,
      "top3_rate_pct": 25.0,
      "avg_rank_score": 62.1,
      "snapshot_count": 8,
      "top3_count": 2
    }
  ]
}

字段	说明
mention_rate_pct	当日该平台我方品牌提及率(0–100)
first_place_rate_pct	当日排首位占比(0–100)
top3_rate_pct	当日进入前 3 占比(0–100)
avg_rank_score	当日加权排名分(无样本时字段缺省)
snapshot_count	当日该平台快照数
top3_count	当日进入前 3 的快照数

5.6 每日排名位置

GET /brands/{brand_id}/rank-positions?days=30

按 (话题 × 平台 × 日期) 给出当日具体排名,粒度比 5.5 更细。

示例响应

{
  "data": [
    {
      "topic_id": "9f4c...e1",
      "keyword": "云端数据库 推荐",
      "topic_type": "industry",
      "date": "2025-12-07",
      "platform": "deepseek",
      "brand_rank": 2,
      "brand_mentioned": true,
      "rank_score": 75.0,
      "total_entities": 10
    }
  ]
}

字段	说明
brand_rank	当日实际位次;仅在被提及时返回,未提及时字段缺省
brand_mentioned	是否提到我方品牌
rank_score	当日该 (话题, 平台) 的加权得分(无样本时字段缺省)
total_entities	当日该 (话题, 平台) 回答里出现的实体总数(分母)

口碑洞察

5.7 口碑概览

GET /brands/{brand_id}/sentiment-overview?days=30

口碑洞察的总览。返回窗口内 AI 回答提及该品牌时的正/中/负分布、口碑健康分、环比、趋势曲线、分平台/分话题分布、(话题×平台)热力图、负面 Top 与近期评价节选、印象词云。与平台前端「口碑洞察」页概览同源。

示例响应

{
  "data": {
    "filter": { "from": "", "to": "", "days": 30 },
    "total": { "positive": 42, "neutral": 18, "negative": 6, "total": 66 },
    "positive_ratio": 63.64,
    "neutral_ratio": 27.27,
    "negative_ratio": 9.09,
    "health_score": 76.52,
    "health_label": "口碑良好",
    "prev_compare": {
      "prev_total": 58,
      "prev_health_score": 71.03,
      "health_score_delta": 5.49,
      "positive_ratio_delta": 4.12,
      "negative_ratio_delta": -2.07,
      "negative_count_delta": -3,
      "total_delta": 8,
      "period_from": "2025-11-05",
      "period_to": "2025-11-19"
    },
    "trend": [
      { "date": "2025-12-07", "positive": 3, "neutral": 1, "negative": 0, "total": 4, "health_score": 87.5 }
    ],
    "by_platform": [
      { "platform": "deepseek", "avg_score": 0.62, "positive": 20, "neutral": 8, "negative": 3, "total": 31 }
    ],
    "by_topic": [
      { "topic_id": "9f4c...e1", "keyword": "示例品牌 口碑怎么样", "avg_score": 0.71, "positive": 12, "neutral": 5, "negative": 2, "total": 19 }
    ],
    "heatmap": {
      "topics": [ { "topic_id": "9f4c...e1", "keyword": "示例品牌 口碑怎么样" } ],
      "platforms": [ "deepseek", "doubao" ],
      "cells": [
        { "topic_id": "9f4c...e1", "platform": "deepseek", "positive": 6, "neutral": 3, "negative": 1, "total": 10, "avg_score": 0.65, "health_score": 82.5 }
      ]
    },
    "negative_top": [
      { "entity_name": "示例品牌", "platform": "deepseek", "topic_id": "9f4c...e1", "topic_keyword": "示例品牌 口碑怎么样", "sentiment": "negative", "context_snippet": "……回答中提到该品牌在售后响应上较慢……", "snapshot_date": "2025-12-07" }
    ],
    "recent_mentions": [
      { "entity_name": "示例品牌", "platform": "doubao", "topic_id": "9f4c...e1", "topic_keyword": "示例品牌 怎么样", "sentiment": "positive", "context_snippet": "……综合体验反馈不错……", "snapshot_date": "2025-12-08" }
    ],
    "keyword_cloud": [
      { "word": "性价比", "weight": 18, "sentiment": "positive" },
      { "word": "客服慢", "weight": 7, "sentiment": "negative" }
    ]
  }
}

字段	说明
filter	回显本次查询条件;`days` 模式下 `from`/`to` 为空串、回 `days`,`from`/`to` 模式下回 `from`+`to`(`days` 缺省);`platforms` 仅在传了 `platform` 时出现
total	窗口内正/中/负及总提及数
positive_ratio / neutral_ratio / negative_ratio	三类占比(0–100)
health_score	口碑健康分:`(positive×100 + neutral×50) / total`,无样本时为 50
health_label	`口碑健康`(≥80) / `口碑良好`(≥60) / `口碑一般`(≥40) / `需要关注`(<40)
prev_compare	与上一段等长窗口的环比;仅当窗口可锚定(传了 `days` 或 `from`/`to`)时返回,全量无窗口时为 null
trend	按日(或按周分桶)的正/中/负序列,每点带当日 health_score
by_platform / by_topic	分平台 / 分话题的正/中/负与平均分
heatmap	(话题 × 平台)矩阵;`topics` 为行、`platforms` 为列、`cells` 为单元格
negative_top	负面评价节选(最多 8 条)
recent_mentions	近期评价节选(最多 30 条)
keyword_cloud	印象词云;`weight` 为词频权重,`sentiment` 为该词的总体情感倾向

口碑健康分把中性按 50 分折算,因此「正多中多负少」的品牌会拿到高分, 负面集中时迅速下滑。prev_compare 的 period_from/period_to 是上一段窗口的实际起止日期,便于接入方自己画环比箭头。

5.8 评价节选

GET /brands/{brand_id}/sentiment-mentions?sentiment=negative&q=售后&page=1&page_size=20

口碑洞察的评价明细。分页返回 AI 回答里提到该品牌的片段(带情感标签与上下文)。在通用 days/from/to/platform 之上另支持:

参数	类型	默认	说明
`topic_id`	string	—	按话题过滤(UUID)
`sentiment`	string	—	`positive` / `neutral` / `negative`
`q`	string	—	对 `context_snippet` 做大小写不敏感子串模糊
`page`	int	1	页码,从 1 起
`page_size`	int	20	每页条数,上限 100

示例响应

{
  "data": {
    "items": [
      {
        "entity_name": "示例品牌",
        "platform": "deepseek",
        "topic_id": "9f4c...e1",
        "topic_keyword": "示例品牌 口碑怎么样",
        "sentiment": "negative",
        "context_snippet": "……回答中提到该品牌在售后响应上较慢……",
        "snapshot_date": "2025-12-07"
      }
    ],
    "total": 6,
    "page": 1,
    "size": 20
  }
}

字段	说明
entity_name	该评价节选里被识别出的实体名(通常即品牌本身)
context_snippet	AI 回答中提及该品牌的上下文片段
snapshot_date	该回答的采集日期(`YYYY-MM-DD`)
total / page / size	总条数 / 当前页 / 当前页条数(分页元信息)

引用来源

5.9 引用来源列表

GET /brands/{brand_id}/citations?days=30

返回 AI 回答里引用到的外部页面统计(支持 from/to/platform)。

示例响应

{
  "data": [
    {
      "source_name": "知乎",
      "source_url": "https://zhuanlan.zhihu.com/p/xxxxx",
      "source_domain": "zhuanlan.zhihu.com",
      "cite_count": 5,
      "keyword": "云端数据库 推荐",
      "platform": "deepseek",
      "is_my_source": false,
      "source_origin": "",
      "source_title": "2025 云端数据库深度横评",
      "source_article_title": "2025 云端数据库深度横评",
      "source_sitename": "知乎",
      "source_match_key": "2025 云端数据库深度横评"
    }
  ]
}

字段	说明
source_name	后台维护的中文展示名(如 `mp.weixin.qq.com → 微信公众号`),没维护时回落为域名
source_url / source_domain	引用页 URL 与域名
cite_count	该来源在窗口内被引用次数
keyword / platform	该引用所属话题词与采集平台
is_my_source	是否命中当前品牌的「我的信源」(URL 精确匹配优先)
source_origin	命中信源的来源类型:`""`(非我的信源) / `manual` / `press_auto`
source_title	网页原始标题
source_article_title	提取后的文章标题(展示用)
source_sitename	原生平台名
source_match_key	规范化匹配键(取消标记时的兜底定位键)

5.10 引用来源汇总

GET /brands/{brand_id}/citations/overview

无时间参数,返回该品牌所有时间累计的引用统计:

{
  "data": {
    "total_count": 1325,
    "source_count": 482,
    "domain_count": 113,
    "topic_count": 14
  }
}

字段	说明
total_count	累计引用总次数
source_count	累计去重来源(URL)数
domain_count	累计去重域名数
topic_count	涉及话题数

5.11 引用来源趋势

GET /brands/{brand_id}/citations/trend?days=30

按 (日期 × 来源展示名) 给出引用计数时间序列,适合画「各引用源随时间的占比」堆叠图(支持 from/to/platform)。

示例响应

{
  "data": [
    { "date": "2025-12-07", "source_name": "知乎", "count": 4 },
    { "date": "2025-12-07", "source_name": "百家号", "count": 2 }
  ]
}

字段	说明
source_name	来源展示名(与 5.9 同口径)
count	该来源当日被引用次数

竞品分析

5.12 发现的竞品

GET /brands/{brand_id}/competitors?days=30

聚合 AI 回答里与我方品牌共同出现过的非自有实体,作为隐式竞品候选。

示例响应

{
  "data": [
    {
      "entity_name": "某竞品 A",
      "mention_count": 28,
      "platform_count": 5,
      "first_seen_date": "2025-09-04",
      "mention_rate_pct": 26.62,
      "avg_rank_score": 14.46,
      "first_position_rate": 4.63,
      "is_our_brand": false,
      "recent_mentions": 9,
      "previous_mentions": 5,
      "previous_window_days": 7,
      "platform_mentions": { "deepseek": 12, "doubao": 8 },
      "daily_trend": [
        {
          "date": "2025-12-07",
          "count": 2,
          "rank_score": 72.0,
          "first_position_rate": 3.7,
          "platform_counts": { "deepseek": 1, "doubao": 1 }
        }
      ]
    }
  ]
}

字段	说明
mention_count	窗口内该竞品被提及总次数
platform_count	窗口内出现的平台数
first_seen_date	首次被采集到的日期
mention_rate_pct	该竞品在全部有效非品牌话题快照中的出现率(0–100)
avg_rank_score	话题口径下的加权排名分(0–100)
first_position_rate	占据首位的快照占比(0–100)
is_our_brand	是否为「我方品牌」(含我方品牌视图时为 true)
recent_mentions / previous_mentions	固定 7 天滚动窗口的提及数(最近 7 天 / 其前的 7 天),用于「上升中」提示;与 `days` 参数无关
previous_window_days	上一段 7 天窗口内实际有采集数据的天数(≤7,取决于采集情况,非请求窗口长度)
platform_mentions	各平台分项(可空对象)
daily_trend	最近 14 天的按日时间序列;`platform_counts` 为当日平台细分

5.13 竞品汇总

GET /brands/{brand_id}/competitors/summary?days=30

窗口内的竞品总数与总提及数(KPI 口径,不受 5.12 的 Top-N 列表截断影响; 支持 days/from/to/platform)。

{
  "data": {
    "total_competitors": 42,
    "total_mentions": 1280
  }
}

字段	说明
total_competitors	窗口内去重竞品数
total_mentions	窗口内竞品被提及总次数

5.14 竞品分平台

GET /brands/{brand_id}/competitors/by-platform?days=30

每个平台下的竞品提及次数与加权排名分(支持 days/from/to/platform)。

示例响应

{
  "data": [
    {
      "platform": "deepseek",
      "entity_name": "某竞品 A",
      "mention_count": 12,
      "avg_rank_score": 15.3,
      "is_our_brand": false
    }
  ]
}

字段	说明
mention_count	该平台下该竞品提及次数
avg_rank_score	该平台下的加权排名分(0–100)
is_our_brand	是否为「我方品牌」

5.15 竞品全量累计

GET /brands/{brand_id}/competitors/overview

无时间参数,返回该品牌所有时间累计的竞品统计:

{
  "data": {
    "total_competitors": 120,
    "total_mentions": 8420,
    "max_platform_count": 6
  }
}

字段	说明
total_competitors	累计去重竞品数
total_mentions	累计竞品提及总次数
max_platform_count	单个竞品覆盖过的最大平台数

对话录屏与原文

5.16 对话录屏与原文

GET /brands/{brand_id}/crawl-replays?date=2025-12-08

返回指定日期(默认今天,Asia/Shanghai)按话题分组、当天计划监测的平台范围，以及每个平台的一条快照 + 录屏 URL，并返回 Markdown 格式的 AI 回答原文。

参数	类型	默认	说明
`date`	string	今天	`YYYY-MM-DD`(Asia/Shanghai);超出近 7 天范围返回空 `topics`

示例响应

{
  "data": {
    "brand_id": "f6c5f69c-...",
    "date": "2025-12-08",
    "retention_days": 7,
    "topics": [
      {
        "topic_id": "9f4c...e1",
        "topic_keyword": "云端数据库 推荐",
        "search_prompt": "云端数据库 推荐 2025",
        "monitoring_platforms": ["deepseek", "doubao"],
        "snapshots": [
          {
            "snapshot_id": "a1b2...c3",
            "platform": "deepseek",
            "video_url": "https://oss.example.com/replay/...?Expires=...&Signature=...",
            "video_preview_url": "https://oss.example.com/replay/...-preview.mp4?...",
            "video_thumb_url": "https://oss.example.com/replay/...-thumb.jpg?...",
            "video_duration_ms": 18420,
            "raw_response": "云端数据库推荐优先考虑……"
          }
        ]
      }
    ]
  }
}

字段	说明
date	实际生效的日期(传空时服务端按今天补齐后回传)
retention_days	可回放天数(固定 7)
topic_keyword / search_prompt	话题词 / 采集时下发的搜索提示词
monitoring_platforms	该监测计划设置的监测平台范围
snapshot_id	快照 ID
platform	采集平台
video_url	录屏可播放地址(OSS 签名 URL,1 小时有效)
video_preview_url / video_thumb_url	预览视频 / 缩略图地址(签名 URL,同样 1 小时)
video_duration_ms	录屏时长(毫秒)
raw_response	该快照对应的 AI 回复原文;原文为空或尚未落库时字段缺省

品牌与话题管理

通用规则一览(与平台一致):

规则	说明
写权限	工作区所有者或协作者可执行;member权限返回 `403 forbidden`
品牌配额	免费版 1 个、基础版 1 个、专业版 50 个;超限 `422 quota_exceeded`
话题字数	`keyword` 最多 20 个字符,`search_prompt` 最多 50 个字符;超限 `400 bad_request`
监测计划配额	免费版 10、基础版 30、专业版 200。超限返回 `422 quota_exceeded`
首次批次	品牌首个话题批次必须同时含 `brand` 与 `industry` 两类；免费版首次必须恰好创建 2 条，否则分别返回 `422 topic_type_required` / `422 initial_free_topic_limit`
双类型保护	删除活跃话题后该品牌必须仍至少保留 1 个品牌词 + 1 个行业词,否则 `422 last_topic_type`
删除 + 24h 冻结	删除的话题额度 24h 后释放(响应回 `quota_releases_at`)
级联删除	删除品牌会级联删其下所有话题
name_confirm	删除品牌需在请求体传 `name_confirm`(=品牌展示名)防误删,不符返回 `400 bad_request`
冻结可删	被冻结的品牌/话题仍可删除;但无法更新

5.17 创建品牌

POST /brands

请求体

{
  "name": "示例品牌",
  "website": "https://example.com",
  "description": "做云端数据库的公司",
  "aliases": ["示例"]
}

字段	类型	必填	说明
name	string	是	品牌展示名(非空)
website	string	否	品牌官网
description	string	否	品牌描述
aliases	string[]	否	品牌别名,最多保留 2 个(去重、不含品牌名本身)

示例响应 201

{
  "data": {
    "id": "f6c5f69c-1234-4abc-9d77-2b1c0c5fdc8a",
    "name": "示例品牌",
    "website": "https://example.com",
    "description": "做云端数据库的公司",
    "is_active": true,
    "created_at": "2025-09-01T03:21:11Z",
    "updated_at": "2025-09-01T03:21:11Z"
  }
}

创建即占用品牌配额。免费/基础版仅 1 个品牌,已有品牌时再创建返回 422 quota_exceeded(带 data),需先删除或升级专业版。

5.18 删除品牌

DELETE /brands/{brand_id}

请求体(需带 name_confirm 防误删)

{ "name_confirm": "示例品牌" }

字段	类型	必填	说明
name_confirm	string	是	必须与品牌展示名完全一致,否则 `400 bad_request`

示例响应 200

{ "data": { "deleted": true, "id": "f6c5f69c-..." } }

品牌及其下所有活跃话题一并删除，数据停更。品牌配额即时释放, 被级联删除的话题额度仍按 24h 冻结窗口释放。

5.19 添加话题

POST /brands/{brand_id}/topics

请求体

{
  "topics": [
    { "keyword": "示例品牌 怎么样", "topic_type": "brand", "monitoring_platforms": ["deepseek", "doubao"] },
    { "keyword": "云端数据库 推荐", "topic_type": "industry", "search_prompt": "云端数据库 推荐 2025", "monitoring_platforms": ["deepseek", "doubao"] }
  ]
}

字段	类型	必填	说明
topics	object[]	是	本次批量添加的话题(至少 1 条)
topics[].keyword	string	是	话题词(非空,最多 20 个字符)
topics[].topic_type	string	是	`brand`(品牌词) / `industry`(行业词)
topics[].search_prompt	string	否	采集时下发的搜索提示词,最多 50 个字符;不传则由系统生成
topics[].monitoring_platforms	string[]	否	初始监测平台范围，至少 1 个；不传时默认全部六个AI平台

示例响应 201

{
  "data": {
    "created": 2,
    "topics": [
      { "id": "9f4c...e1", "keyword": "示例品牌 怎么样", "topic_type": "brand", "is_active": true, "monitoring_enabled": true, "monitoring_platforms": ["deepseek", "doubao"], "created_at": "2025-09-01T03:25:00Z" },
      { "id": "a1b2...c3", "keyword": "云端数据库 推荐", "topic_type": "industry", "is_active": true, "monitoring_enabled": true, "monitoring_platforms": ["deepseek", "doubao"], "created_at": "2025-09-01T03:25:00Z" }
    ]
  }
}

品牌首个话题批次必须同时含 brand + industry,否则 422 topic_type_required；免费版首次批次必须恰好为 2 条，超过或不足返回 422 initial_free_topic_limit。首次创建完成后，免费版可在 10 条总配额内继续添加。超出套餐话题配额返回 422 quota_exceeded(带 data,含已用/上限/套餐)。 keyword 或 search_prompt 超出字数限制时返回 400 bad_request,本批次不会写入任何话题。 monitoring_platforms 会去除首尾空白、转为小写、去重并按标准平台顺序保存；显式传空数组或未知平台返回 400 bad_request。新话题默认开启监测。删除的话题额度 24h 内仍占用,新增时一并计入。

5.20 编辑监测计划

PUT /topics/{topic_id}/monitoring-plan

更新单个话题的用户监测开关或 AI 平台范围。该接口不会修改话题的生命周期状态 is_active，也不开放监测频率；当前频率固定为每日。

请求体

{
  "monitoring_enabled": true,
  "monitoring_platforms": ["deepseek", "doubao"]
}

字段	类型	必填	说明
monitoring_enabled	bool	条件必填	用户监测开关；省略时保持原值
monitoring_platforms	string[]	条件必填	监测平台范围，至少 1 个；省略时保持原值

两个字段均可单独传入，但至少需要提供一个。平台值会去除首尾空白、转为小写、去重，并按 deepseek、doubao、wenxin、kimi、qianwen、yuanbao 的标准顺序返回。显式传空数组、传未知平台或空请求体均返回 400 bad_request。

示例响应 200

{
  "data": {
    "id": "9f4c...e1",
    "keyword": "云端数据库 推荐",
    "topic_type": "industry",
    "is_active": true,
    "monitoring_enabled": true,
    "monitoring_platforms": ["deepseek", "doubao"],
    "created_at": "2025-09-01T03:25:00Z"
  }
}

5.21 删除话题

DELETE /topics/{topic_id}

无请求体。

示例响应 200

{
  "data": {
    "deleted": true,
    "id": "9f4c...e1",
    "quota_releases_at": "2025-09-02T03:25:00Z"
  }
}

字段	说明
deleted	固定 `true`
id	被删除的话题 ID
quota_releases_at	活跃话题额度释放时间(约 24h 后);冻结话题删除不占用额度,字段缺省

删除话题后,若该品牌将不再具备品牌词或行业词,返回 422 last_topic_type (品牌下需要至少有一个品牌词和一个行业词)。冻结话题删除不受此约束。

6. 调用示例

curl

curl -H "X-API-Key: $API_KEY" \
  "https://geo.yueyuezi.com/open-api/v1/brands"

curl -H "X-API-Key: $API_KEY" \
  "https://geo.yueyuezi.com/open-api/v1/brands/<brand_id>/trend?days=14"

curl -H "X-API-Key: $API_KEY" \
  "https://geo.yueyuezi.com/open-api/v1/brands/<brand_id>/sentiment-mentions?sentiment=negative&page_size=50"

curl -H "X-API-Key: $API_KEY" \
  "https://geo.yueyuezi.com/open-api/v1/brands/<brand_id>/crawl-replays?date=2025-12-08"

# 创建品牌
curl -X POST -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"示例品牌","website":"https://example.com"}' \
  "https://geo.yueyuezi.com/open-api/v1/brands"

# 删除品牌(需带 name_confirm)
curl -X DELETE -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"name_confirm":"示例品牌"}' \
  "https://geo.yueyuezi.com/open-api/v1/brands/<brand_id>"

# 添加话题(首个批次需同时含 brand + industry)
curl -X POST -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"topics":[{"keyword":"示例品牌 怎么样","topic_type":"brand","monitoring_platforms":["deepseek","doubao"]},{"keyword":"云端数据库 推荐","topic_type":"industry","monitoring_platforms":["deepseek","doubao"]}]}' \
  "https://geo.yueyuezi.com/open-api/v1/brands/<brand_id>/topics"

# 编辑监测计划(字段可单独传入)
curl -X PUT -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"monitoring_enabled":true,"monitoring_platforms":["deepseek","doubao"]}' \
  "https://geo.yueyuezi.com/open-api/v1/topics/<topic_id>/monitoring-plan"

# 删除话题
curl -X DELETE -H "X-API-Key: $API_KEY" \
  "https://geo.yueyuezi.com/open-api/v1/topics/<topic_id>"

Python

import os, requests, time

API_KEY = os.environ["API_KEY"]
BASE = "https://geo.yueyuezi.com/open-api/v1"
H = {"X-API-Key": API_KEY}

def get(path, **params):
    url = f"{BASE}{path}"
    while True:
        r = requests.get(url, headers=H, params=params or None, timeout=10)
        if r.status_code != 429:
            r.raise_for_status()
            return r.json()["data"]
        time.sleep(int(r.headers.get("Retry-After", "1")))

brands = get("/brands")
brand_id = brands[0]["id"]

trend = get(f"/brands/{brand_id}/trend", days=14)
sentiment = get(f"/brands/{brand_id}/sentiment-overview", days=30)
replays = get(f"/brands/{brand_id}/crawl-replays", date="2025-12-08")

限流处理

单密钥 1 QPS,超限返回 429 rate_limited 并带 Retry-After 头(秒)。推荐对每次请求都做 429 重试(见上方 Python 示例的 get 封装)。

第二部分:媒体发稿 API

媒体发稿接口与第一部分共用 Base URL、API Key、工作区切换、响应结构和 1 QPS 限流。接口开放媒体查询、发稿和订单状态查询。

1. 计价与扣款规则

API Key 就是在「左下角个人中心 -> API Key 管理」创建的账户 Key,无需单独申请发稿密钥。
GET /press/media 返回当前活动工作区在界面上看到的价格:unit_price_cents 即实际应付价。免费版按基础价,基础版/专业版按折扣价(当前为 5.5 折)。
POST /press/orders 固定从 API Key 所属账户的钱包余额扣款。
使用 X-Active-Workspace 时,品牌归属和媒体价格跟随活动工作区,钱包仍是 API Key 所属账户的钱包,与该账户在界面切换工作区后发稿的规则一致。
余额不足返回 402 insufficient_balance,不会创建订单或扣除部分金额。
金额字段单位默认均为「分」,币种固定 CNY。

2. 媒体资源列表

GET /press/media

查询参数

媒体列表没有必填查询参数;不传参数时默认查询网站媒体第一页。枚举筛选参数应传下方列出的 value 编码,不能传中文名称;不需要某项筛选时直接省略该参数或传空字符串。

参数	类型	必填	默认	适用范围	说明
media_type	string(enum)	否	`website`	全部	`website`(网站媒体) / `wemedia`(自媒体)
title	string	否	-	全部	媒体名称关键词,模糊匹配
remarks	string	否	-	全部	媒体备注关键词,模糊匹配
industry	string(enum)	否	-	全部	网站媒体:行业领域;自媒体:平台
portal	string(enum)	否	-	全部	网站媒体:综合门户;自媒体:行业类型
region	string(enum)	否	-	全部	所在地区;两类媒体的港澳台编码不同
entrance	string(enum)	否	-	全部	网站媒体:入口级别;自媒体:粉丝量
indexed	string(enum)	否	-	全部	网站媒体:收录情况;自媒体:阅读量
link	string(enum)	否	-	全部	网站媒体:链接类型;自媒体:账号认证
speed	string(enum)	否	-	全部	网站媒体:发稿速度;自媒体:官方媒体
special	string(enum)	否	-	全部	网站媒体:特殊行业;自媒体:其他能力
other	string(enum)	否	-	仅 `website`	网站媒体其它能力;自媒体不支持,查询自媒体时不要传
price_min	string(number)	否	-	全部	最低折扣价,单位元,如 `21`;可与 `price_max` 单独或组合使用
price_max	string(number)	否	-	全部	最高折扣价,单位元,如 `100`;可与 `price_min` 单独或组合使用
sort	string(enum)	否	-	全部	`price`(价格) / `publish_rate`(出稿率) / `weight`(权重)
page_no	int	否	`1`	全部	页码,最小 `1`
page_size	int	否	`20`	全部	每页数量,范围 `1-200`

网站媒体筛选枚举(`media_type=website`)

参数	业务含义	可用 value -> 名称
industry	行业领域	`1001` IT科技; `1002` 游戏网站; `1003` 财经商业; `1004` 汽车网站; `1005` 娱乐休闲; `1006` 新闻资讯; `1007` 健康医疗; `1008` 房产家居; `1009` 亲子母婴; `1010` 教育培训; `1011` 食品餐饮; `1012` 酒店旅游; `1013` 女性时尚; `1014` 生活消费; `1015` 公益; `1016` 体育运动; `1017` 工业贸易; `1018` 文化艺术; `1019` 套餐系列; `1020` 最新秒杀; `1021` 十元专区; `1022` 区块链; `1023` 其他
portal	综合门户	`2001` 腾讯网; `2002` 新浪网; `2003` 网易网; `2004` 搜狐网; `2005` 凤凰网; `2006` 人民网; `2007` 央视网; `2008` 中国广播网; `2009` 中国新闻网; `2010` 新华网; `2011` 中国日报网; `2012` 光明网; `2013` 中国青年网; `2014` 环球网; `2015` 千龙网; `2016` 北青网; `2017` 中国经济网; `2018` 国际在线; `2019` 和讯网; `2020` 中国网; `2021` 中华网; `2022` 东方网; `2023` 大众网; `2024` 慧聪网; `2025` 垂直媒体; `2026` 海外媒体; `2027` 其他门户; `2029` 人民日报客户端; `2030` zaker号; `2031` 官方百家号; `2032` 荆楚网(湖北日报)
region	所在地区	`3001` 综合全国; `3002` 北京; `3003` 上海; `3004` 重庆; `3005` 天津; `3006` 海南; `3007` 广东; `3008` 广西; `3009` 湖南; `3010` 湖北; `3011` 福建; `3012` 江西; `3013` 浙江; `3014` 安徽; `3015` 江苏; `3016` 河南; `3017` 河北; `3018` 山东; `3019` 山西; `3020` 贵州; `3021` 四川; `3022` 青海; `3023` 西藏; `3024` 辽宁; `3025` 吉林; `3026` 陕西; `3027` 甘肃; `3028` 宁夏; `3029` 黑龙江; `3030` 内蒙古; `3031` 云南; `3032` 新疆; `3033` 港澳台
entrance	入口级别	`4001` 没有入口; `4002` 首页入口; `4003` 频道入口; `4004` 上级入口
indexed	收录情况	`5001` 不包网页收录; `5002` 包网页收录; `5003` 不包资讯收录; `5004` 包资讯收录
link	链接类型	`6001` 不可带网址; `6003` 可带网址
speed	发稿速度	`7001` 1小时; `7002` 2小时; `7012` 12小时; `7024` 当日; `7048` 次日; `7049` 48小时以上
special	特殊行业	`8001` 金融; `8002` 微商; `8003` 留学; `8004` 医疗; `8005` 加盟
other	其它能力	`9001` 周末可发; `9002` 节日可发; `9003` 晚上可发; `9004` 文字链/焦点图; `9005` 白名单来源; `9006` 可带视频; `9007` 移动端媒体; `9008` 时效3个月以上; `9009` 可发GEO排名

自媒体筛选枚举(`media_type=wemedia`)

参数	业务含义	可用 value -> 名称
industry	平台	`1006` 今日头条; `1005` 百家号; `1009` 新浪号; `1003` 网易号; `1001` 腾讯号; `1020` 凤凰号; `1023` 懂车帝; `1012` zaker; `1011` 知乎号; `1007` 微博; `1004` 搜狐网; `1008` 一点资讯; `1002` 哔哩哔哩; `1010` 小红书; `1013` 豆瓣; `1015` 什么值得买; `1016` 东方财富号; `1022` 车家号; `1018` 中金在线号; `1019` 雪球号; `1014` UC头条; `1017` 微信公众号; `1021` 其他
portal	行业类型	`2001` 文化; `2002` 历史; `2010` 健康; `2004` 财经; `2005` 科技; `2006` 体育; `2007` 汽车; `2008` 娱乐; `2009` 时尚; `2003` 三农; `2011` 教育; `2012` 母婴; `2013` 美食; `2014` 旅游; `2015` 公益; `2016` 游戏; `2017` 动漫; `2018` 社会; `2019` 房产; `2020` 职场; `2021` 情感; `2022` 搞笑; `2023` 新闻; `2024` 家居; `2025` 生活
region	所在地区	`3001` 综合全国; `3002` 北京; `3003` 上海; `3004` 重庆; `3005` 天津; `3006` 海南; `3007` 广东; `3008` 广西; `3009` 湖南; `3010` 湖北; `3011` 福建; `3012` 江西; `3013` 浙江; `3014` 安徽; `3015` 江苏; `3016` 河南; `3017` 河北; `3018` 山东; `3019` 山西; `3020` 贵州; `3021` 四川; `3022` 青海; `3023` 西藏; `3024` 辽宁; `3025` 吉林; `3026` 陕西; `3027` 甘肃; `3028` 宁夏; `3029` 黑龙江; `3030` 内蒙古; `3031` 云南; `3032` 新疆; `3033` 台湾; `3034` 香港; `3035` 澳门
entrance	粉丝量	`4001` 0-1000; `4005` 1000-5000; `4010` 5001-1万; `4050` 1万-5万; `4100` 5万-10万; `4006` 10-100万; `4007` 100万-500万; `4008` 500万-1000万; `4009` 1000万以上
indexed	阅读量	`5001` 0-1000; `5005` 1001-5000; `5010` 5001-1万; `5050` 1万-5万; `5100` 5万-10万; `5101` 10万以上
link	账号认证	`6001` 已认证; `6002` 未认证
speed	官方媒体	`7001` 官方媒体; `7002` 非官方媒体
special	其它能力	`8001` 可发视频; `8002` 周末可发; `8003` 节假日可发; `8004` 黄V认证; `8005` 秒出稿; `8006` 可发GEO排名
other	不支持	自媒体的该筛选组已禁用,不要传 `other`

请求示例:

GET /press/media?media_type=website&industry=1001&region=3002&indexed=5002&page_no=1&page_size=20

示例响应 `200`

{
  "data": {
    "total": 128,
    "page_no": 1,
    "page_size": 20,
    "resources": [
      {
        "id": "rsc_12345",
        "media_type": "website",
        "name": "示例科技媒体",
        "unit_price_cents": 5500,
        "base_price_cents": 10000,
        "discount_price_cents": 5500,
        "region": "全国",
        "industry": "科技",
        "portal": "综合门户",
        "indexed": "新闻源收录",
        "link_type": "可带链接",
        "publish_speed_hours": 24,
        "publish_rate": 96,
        "pc_weight": 4,
        "wap_weight": 4,
        "remarks": "周末可发"
      }
    ]
  }
}

下单时把所选资源的 id、name、media_type 原样放进 resources 表单字段。 base_price_cents 和 discount_price_cents 用于展示价格体系;结算只看 unit_price_cents,且下单时仍会由服务端重新验价。

3. 创建发稿订单

POST /press/orders
Content-Type: multipart/form-data

请求头

请求头	必填	说明
X-API-Key	是	账户 API Key;也可用 `Authorization: Bearer`
X-Active-Workspace	否	活动工作区的 8 位公开 ID 或 UUID

multipart 表单字段

字段	类型	必填	说明
file	file	是	`.docx` 文档,最大 10MB
resources	string(JSON)	是	1-50 个媒体对象的 JSON 数组
title	string	否	稿件标题,最多 50 字;不传时取 DOCX 首个标题段落,没有标题样式则取首个正文段落
brand_id	UUID	是	发稿订单归属品牌;必须属于当前活动工作区
remark	string	否	给编辑/运营的备注

resources 的 JSON 结构:

[
  {"id":"rsc_12345","name":"示例科技媒体","media_type":"website"},
  {"id":"rsc_67890","name":"示例公众号","media_type":"wemedia"}
]

接口不接受 content_html 或其它富文本字段,服务端会解析 DOCX 的段落、标题、粗体/斜体/上下标、列表、链接、表格和常见内嵌图片 (jpg/jpeg/png/gif/webp);图片会转存到投稿图片服务后再随正文自动投稿。修订模式下已删除的文字不会进入稿件。页眉、页脚、浮动文本框、宏和页面排版参数不作为正文传输。

curl 示例

curl -X POST \
  -H "X-API-Key: $API_KEY" \
  -F 'file=@./article.docx;type=application/vnd.openxmlformats-officedocument.wordprocessingml.document' \
  -F 'title=示例品牌发布新产品' \
  -F 'brand_id=<brand_id>' \
  -F 'remark=请保留文中数据表格' \
  -F 'resources=[{"id":"rsc_12345","name":"示例科技媒体","media_type":"website"}]' \
  "https://geo.yueyuezi.com/open-api/v1/press/orders"

示例响应 `200`

{
  "data": {
    "order_no": "UPRS20260722153000A1B2C3D4",
    "title": "示例品牌发布新产品",
    "amount_cents": 5500,
    "currency": "CNY",
    "order_status": "paid",
    "paid_at": "2026-07-22T07:30:01Z",
    "created_at": "2026-07-22T07:30:01Z",
    "updated_at": "2026-07-22T07:30:01Z",
    "publishing_items": [
      {
        "press_no": "UGPR20260722A1B2C3D4E5F6",
        "resource_id": "rsc_12345",
        "media_name": "示例科技媒体",
        "media_type": "website",
        "price_cents": 5500,
        "publish_status": "pending"
      }
    ]
  }
}

重复调用约束

接口当前不接收也不识别跨请求去重键,每次成功调用都会创建新的订单并扣款。
调用方应在自身系统中按业务单号防重,并避免按钮双击、任务重跑或并发提交同一稿件。

4. 查询发稿订单状态

GET /press/orders/{order_no}

order_no 使用创建接口返回的 UPRS... 批次订单号。

响应结构与创建订单相同。publishing_items 中每个媒体都的发稿有独立的发稿编号press_no,

发布状态

publish_status	说明
pending	待安排
submitted	已安排/处理中
published	已发布;同时返回 `published_url` 和 `published_at`
rejected	已退稿;同时返回 `failure_reason`
refunded	已退款;退款由平台后台执行,API 仅反映最终状态

order_status 通常为 paid;整单退款后为 refunded。单个媒体退款时订单仍可能保持 paid,应以各条 publishing_items[].publish_status 为准。

5. 发稿错误码

HTTP	code	是否可直接重试	说明
400	invalid_multipart / missing_file / invalid_docx	否	multipart 或 DOCX 无效
400	missing_brand_id	否	缺少必填的品牌归属;补充当前工作区的 `brand_id` 后重新调用
400	invalid_resources / invalid_request / unsupported_field	否	媒体、标题或字段不合法
402	insufficient_balance	否	钱包余额不足;本次不会创建订单,充值后可重新调用
403	brand_forbidden	否	`brand_id` 不属于当前活动工作区或当前 API Key 无权访问
404	not_found	否	`brand_id` 对应品牌不存在或已删除
404	order_not_found	否	订单不存在或不属于该 API Key 账户
413	file_too_large / docx_expanded_too_large	否	文件或解压内容超过限制
429	rate_limited	是	请求未执行;按 `Retry-After` 延迟后重试
503	press_unavailable	是	媒体发稿服务暂不可用;本次未创建订单,可稍后重试
500	internal_error	否	结果可能不确定,不要自动重试;请联系平台核查

独角兽GEO - OpenAPI

第一部分：数据监测与分析API

#1. 基本信息

#2. 鉴权

#2.1 切换工作区(可选)

#3. 通用响应格式

#4. 通用查询参数

#5. 接口列表

#品牌数据

#5.1 品牌列表

#5.2 品牌详情

#5.3 话题列表

#5.4 排名概览(按话题)

#5.5 品牌整体趋势

#5.6 每日排名位置

#口碑洞察

#5.7 口碑概览

#5.8 评价节选

#引用来源

#5.9 引用来源列表

#5.10 引用来源汇总

#5.11 引用来源趋势

#竞品分析

#5.12 发现的竞品

#5.13 竞品汇总

#5.14 竞品分平台

#5.15 竞品全量累计

#对话录屏与原文

#5.16 对话录屏与原文

#品牌与话题管理

#5.17 创建品牌

#5.18 删除品牌

#5.19 添加话题

#5.20 编辑监测计划

#5.21 删除话题

#6. 调用示例

#curl

#Python

#限流处理

第二部分:媒体发稿 API

#1. 计价与扣款规则

#2. 媒体资源列表

#查询参数

#网站媒体筛选枚举(media_type=website)

#自媒体筛选枚举(media_type=wemedia)

#示例响应 200

#3. 创建发稿订单

#请求头

#multipart 表单字段

#curl 示例

#示例响应 200

#重复调用约束

#4. 查询发稿订单状态

#发布状态

#5. 发稿错误码

1. 基本信息

2. 鉴权

2.1 切换工作区(可选)

3. 通用响应格式

4. 通用查询参数

5. 接口列表

品牌数据

5.1 品牌列表

5.2 品牌详情

5.3 话题列表

5.4 排名概览(按话题)

5.5 品牌整体趋势

5.6 每日排名位置

口碑洞察

5.7 口碑概览

5.8 评价节选

引用来源

5.9 引用来源列表

5.10 引用来源汇总

5.11 引用来源趋势

竞品分析

5.12 发现的竞品

5.13 竞品汇总

5.14 竞品分平台

5.15 竞品全量累计

对话录屏与原文

5.16 对话录屏与原文

品牌与话题管理

5.17 创建品牌

5.18 删除品牌

5.19 添加话题

5.20 编辑监测计划

5.21 删除话题

6. 调用示例

curl

Python

限流处理

1. 计价与扣款规则

2. 媒体资源列表

查询参数

网站媒体筛选枚举(`media_type=website`)

自媒体筛选枚举(`media_type=wemedia`)

示例响应 `200`

3. 创建发稿订单

请求头

multipart 表单字段

curl 示例

示例响应 `200`

重复调用约束

4. 查询发稿订单状态

发布状态

5. 发稿错误码