AI 监控 API 标准参考文档

文档目录

• 快速开始
• API 概述
• 提交批量监控任务
• 查询任务状态
• 停止监控任务
• 获取任务结果
• 获取子任务结果
• 获取任务列表
• Callback 回调
• 获取可用区域列表
• 费用对账
• 查询支持的模型列表
• 错误处理
• 使用指南
• 更新日志

接口速览

快速开始

欢迎使用 AI 监控 API — 统一接口，覆盖主流 AI 大模型平台的监控与数据采集。

• 统一接口：一套 API 对接 10+ 主流 AI 平台，无需逐一适配

• 实时监控：异步任务引擎 + 回调通知，秒级感知平台响应变化

• 灵活配置：按平台、模式、区域自由组合，精准覆盖业务场景

核心能力

快速接入（3 步上手）

第 1 步：获取 Token

访问控制台注册账户，在「API 管理」中获取 Bearer Token。

第 2 步：提交监控任务

curl -X POST "https://{API_DOMAIN}/api/business/monitor/task/batch/shared" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompts": ["人工智能的发展趋势"],
    "platforms": [
      {"platform": "deepseek", "mode": "search", "screenshot": 1}
    ]
  }'

成功响应：

{
  "success": true,
  "code": 200,
  "message": "批量任务已提交",
  "data": {
    "taskId": "ec617e1996174c129a872680fa27078e",
    "totalTask": 1,
    "status": "pending",
    "pollUrl": "/api/business/monitor/task/status/ec617e1996174c129a872680fa27078e"
  }
}

第 3 步：获取结果

轮询 pollUrl 直到 status 变为 completed，然后获取完整结果：

curl -X GET "https://{API_DOMAIN}/api/business/monitor/task/status/{taskId}" \
  -H "Authorization: Bearer YOUR_TOKEN"

curl -X GET "https://{API_DOMAIN}/api/business/monitor/task/result/{taskId}" \
  -H "Authorization: Bearer YOUR_TOKEN"

支持的 AI 平台

持续接入中更多 AI 平台正在对接中，敬请期待。

监控模式

建议使用search和reasoning_search（这两种模式下，大模型会返回信源）；standard和reasoning 模式下，大模型不会返回信源。

国内模型费用说明

按子任务计费：基础费用为 0.117 元/次；使用 reasoning 或 reasoning_search 模式时，额外加收 0.117 元/次；开启截图时额外加收 0.117 元/次。

例如：提交 1 个 prompt 到 1 个平台，使用 reasoning_search 模式并开启截图，则费用为 0.117（基础费用）+ 0.117（深度思考）+ 0.117（截图）= 0.351 元。

海外模型费用说明

因海外模型综合成本较高，新增模型的标准定价高于现有国内模型，详见下表：

• 联网搜索 / 深度思考 / 联网搜索+深度思考：标准定价 0.78 元/次；折扣结算价 0.312 元/次。

• 带截图：标准定价 1.04 元/次；折扣结算价 0.416 元/次。

以上折扣结算价为最终计费标准，如有疑问，欢迎随时与我们沟通。

常见错误码

使用建议

提交策略

系统支持单次任务同时包含多个提示词与多个平台，但为保障整体完成率，建议以「1 个提示词 × 1 个平台」为单位提交任务，避免大批量提交时因个别子任务异常拖慢整体进度。

自动重试

任务执行失败后系统会自动重试，每次重试间隔约 5 分钟，最多重试 10 次，无需手动干预。

结果获取

支持两种获取方式，可按需混用：

Callback 具备自动重试机制，失败后最多重试 7 次，重试间隔依次为：15s → 1min → 5min → 15min → 1h → 4h → 12h。

详细配置见 Callback 回调。

质量监控与自动重跑

我们会持续监控各平台的答案质量（包括信源缺失、深度思考缺失比例等）。当监控到某平台当日数据指标异常时，系统将自动重跑缺失部分的任务，并通过 Callback 推送最新答案（仅限已配置回调地址的任务），全力保障当日任务高质量、100% 完成。

排队与支持

平台高峰期压力较大时，任务可能短暂进入排队状态。如需调整任务优先级，或遇到任何问题，欢迎随时联系我们——各时段均有同事在线监控，会第一时间响应。

深入探索

• 遇到问题？欢迎联系技术支持团队

---

AI 监控 API 概述

本文档描述了AI 监控任务相关的后端接口，用于批量提交监控任务、查询任务状态和获取监控结果。支持多平台、多模式的AI监控能力。

接口信息

• Base URL: https://{API_DOMAIN}/api/business/monitor

• 认证方式: Bearer Token

• 请求头: Authorization: Bearer

• 响应格式: JSON

监控模式说明

建议使用search和reasoning_search（这两种模式下，大模型会返回信源）；standard和reasoning 模式下，大模型不会返回信源。

国内模型费用说明

按子任务计费：基础费用为 0.117 元/次；使用 reasoning 或 reasoning_search 模式时，额外加收 0.117 元/次；开启截图时额外加收 0.117 元/次。

例如：提交 1 个 prompt 到 1 个平台，使用 reasoning_search 模式并开启截图，则费用为 0.117（基础费用）+ 0.117（深度思考）+ 0.117（截图）= 0.351 元。

海外模型费用说明

因海外模型综合成本较高，新增模型的标准定价高于现有国内模型，详见下表：

• 联网搜索 / 深度思考 / 联网搜索+深度思考：标准定价 0.78 元/次；折扣结算价 0.312 元/次。

• 带截图：标准定价 1.04 元/次；折扣结算价 0.416 元/次。

以上折扣结算价为最终计费标准，如有疑问，欢迎随时与我们沟通。

支持的 AI 平台列表

商品/视频/搜索词采集统计

Web 端

各 AI 平台的视频、商品和搜索词采集支持情况如下：

---

提交批量监控任务

接口地址: POST /task/batch/shared

接口描述: 提交批量监控任务，支持多个问题共享相同的平台配置，自动创建子任务并异步执行。任务完成后可通过回调接收推送结果，详见 Callback 回调。

需要认证: 是

请求参数

请求示例1：基础批量监控（仅提交提示词与平台配置，不涉及品牌分析）:

适用场景：仅需批量执行多个提示词在各 AI 平台的查询，无需跟踪品牌在 AI 回答中的表现。

{
    "prompts": [
        "请帮我搜索最新款 iPhone型号，以及 iOS 版本",
        "请帮我推荐一款智能手机"
    ],
    "platforms": [
      {"platform": "doubao", "mode": "reasoning_search", "screenshot": 1},
      {"platform": "yuanbao", "mode": "search", "screenshot": 1}
    ],
    "consumerTaskId": "consumerTask202608050001"
}

请求示例2：品牌监控（同时配置监控关键词、别名与竞品词）:

适用场景：需要跟踪「监控词」及其「竞品」在 AI 回答中的提及位置、情感倾向、竞品排名等品牌分析指标，会在子任务结果中返回 mentionPosition、sentiment、competitorRankings 等品牌分析字段；同时配置 callbackUrl，在任务完成后异步接收推送结果。

{
    "monitorKeywords": "华为",
    "monitorKeywordAliases": ["HUAWEI", "华为手机"],
    "competitors": [
        {
            "name": "小米",
            "aliases": ["Xiaomi", "小米手机"]
        },
        {
            "name": "苹果",
            "aliases": ["Apple", "iPhone"]
        }
    ],
    "prompts": [
        "目前市场上销量较高的手机品牌有哪些"
    ],
    "platforms": [
        {"platform": "doubao", "mode": "reasoning_search", "screenshot": 1}
    ],
    "callbackUrl": "https://your-domain.com/callback"
}

参数说明:

PlatformConfig 对象说明:

CompetitorBrand 对象说明

支持的 AI 平台列表

参数去重规则

系统会对提交的参数自动去重处理，确保不会为同一问题重复创建相同平台的监控任务：

• platforms 去重：按 platform 名称（不区分大小写）去重，保留首次出现的配置。例如提交 3 个 deepseek + 1 个 kimi，实际只会创建 deepseek 和 kimi 共 2 个平台的任务

• 任务数计算：totalTask = prompts数量 × 去重后的platforms数量，请以响应中返回的 totalTask 为准

响应结果

{
    "success": true,
    "code": 200,
    "message": "批量任务已提交",
    "data": {
        "taskId": "05c517d143cd4f229786d294942b5a96",
        "consumerTaskId": "consumerTask202606300001",
        "totalTask": 1,
        "status": "pending",
        "pollUrl": "/api/business/monitor/task/status/05c517d143cd4f229786d294942b5a96",
        "subTaskList": [
            {
                "subTaskId": "1037398",
                "prompt": "目前市场上销量较高的手机品牌有哪些",
                "platform": "doubao",
                "mode": "reasoning_search",
                "status": "pending",
                "monitorKeywords": "华为",
                "monitorKeywordAliases": [
                    "HUAWEI",
                    "华为手机"
                ],
                "competitors": [
                    {
                        "name": "小米",
                        "aliases": [
                            "Xiaomi",
                            "小米手机"
                        ]
                    },
                    {
                        "name": "苹果",
                        "aliases": [
                            "Apple",
                            "iPhone"
                        ]
                    }
                ]
            }
        ],
        "callbackUrl": "https://your-domain.com/callback"
    }
}

响应字段说明:

提交幂等

为避免网络重试或超时重发导致重复建单、重复扣费，提交接口支持通过 consumerTaskId 实现幂等。

consumerTaskId 仅用于提交幂等。请保存提交响应中的 taskId，并使用 taskId 查询任务状态和结果。

使用 consumerTaskId

由客户端为每次业务提交生成一个唯一的 consumerTaskId（8~64 位，仅允许字母和数字）：

• 相同 consumerTaskId：直接返回已创建的任务（message 为 "任务已存在"），不重复扣费、不重复创建子任务。

提示建议将 consumerTaskId 与您业务系统中的订单号或请求流水号绑定。一次业务提交固定一个 consumerTaskId，重试时复用同一个值即可获得幂等保证；查询任务时仍使用系统返回的 taskId。

---

查询任务状态

接口地址: GET /task/status/{taskId}

接口描述: 查询批量任务的执行状态和子任务进度

需要认证: 是

请求参数

路径参数:

响应结果

成功响应:

{
    "success": true,
    "code": 200,
    "message": "操作成功",
    "data": {
        "taskId": "5a85cdd0ed9249cfb69daaeca2b91a09",
        "consumerTaskId": "consumerTask202606300001",
        "status": "completed",
        "message": "任务进度: 2/2 已完成, 0 失败",
        "totalItems": 2,
        "completedItems": 2,
        "failedItems": 0,
        "createdAt": 1781080844000,
        "completedAt": 1781082052000,
        "subTaskList": [
            {
                "subTaskId": "1037392",
                "prompt": "目前市场上销量较高的手机品牌有哪些",
                "platform": "doubao",
                "mode": "reasoning_search",
                "status": "completed",
                "monitorKeywords": "华为",
                "monitorKeywordAliases": [
                    "HUAWEI",
                    "华为手机"
                ],
                "competitors": [
                    {
                        "name": "小米",
                        "aliases": [
                            "Xiaomi",
                            "小米手机"
                        ]
                    },
                    {
                        "name": "苹果",
                        "aliases": [
                            "Apple",
                            "iPhone"
                        ]
                    }
                ]
            }
        ]
    }
}

响应字段说明:

任务状态值:

轮询建议

建议每 5-10 秒轮询一次状态接口，避免过于频繁的请求。当 status 为 completed、partial_completed、failed 或 stopped 时，可以获取最终结果。

---

停止监控任务

接口地址: PUT /task/{taskId}/stop

接口描述: 停止一个尚未结束的批量监控任务。停止操作会终止未完成的子任务调度 （已经完成的子任务结果仍然保留并可正常查询）。

需要认证: 是

请求参数

路径参数:

响应结果

成功响应:

{
    "success": true,
    "code": 200,
    "message": "操作成功",
    "data": "任务已停止，影响子任务 2 个"
}

响应字段说明:

业务规则

• 主任务 processing 状态可停止：当主任务处于 processing 时，仍可调用本接口停止任务；停止动作作用于子任务调度层。

• 仅拦截未分配（pending）子任务：只有状态为 pending（未被节点分配/调度）的子任务会被立即停止；已进入 assigned（已分配，正在运行中）的子任务无法被中断，仍可能执行完成并计费。

• 已完成子任务不受影响：状态为 completed、success 的子任务不受影响，其答案、信源、截图等结果继续保留并可查询。

• 已结束任务不可停止：当任务整体状态已是 completed、partial_completed、failed 时，调用本接口将返回错误「任务已结束，不能停止」。

• 停止后状态冻结：任务被停止后整体状态变为 stopped，后续查询状态/结果接口不会再自动推进主任务状态；已产出的子任务结果仍会继续展示。

停止后查询说明

停止任务后，再次调用查询任务状态或获取任务结果接口时：

• 任务整体 status 为 stopped

• completedItems / failedItems 按停止时刻已产出的可见结果重新统计

• 子任务列表中： 已完成的子任务 status 保持为 completed

• 被停止的未完成子任务 status 为 stopped

查询状态响应示例:

{
    "success": true,
    "code": 200,
    "message": "操作成功",
    "data": {
        "taskId": "ec617e1996174c129a872680fa27078e",
        "status": "stopped",
        "message": "任务已停止",
        "totalItems": 4,
        "completedItems": 2,
        "failedItems": 0,
        "createdAt": 1769757913000,
        "completedAt": null,
        "subTaskList": [
            {
                "subTaskId": "4124831",
                "prompt": "请帮我搜索最新款 iPhone型号，以及 iOS 版本",
                "platform": "doubao",
                "mode": "reasoning_search",
                "status": "completed"
            },
            {
                "subTaskId": "4124832",
                "prompt": "请帮我搜索最新款 iPhone型号，以及 iOS 版本",
                "platform": "yuanbao",
                "mode": "search",
                "status": "completed"
            },
            {
                "subTaskId": "4124833",
                "prompt": "请帮我推荐一款智能手机",
                "platform": "doubao",
                "mode": "reasoning_search",
                "status": "stopped"
            },
            {
                "subTaskId": "4124834",
                "prompt": "请帮我推荐一款智能手机",
                "platform": "yuanbao",
                "mode": "search",
                "status": "stopped"
            }
        ]
    }
}

失败响应示例

任务不存在:

{
    "success": false,
    "code": 404,
    "message": "任务不存在"
}

无权操作:

{
    "success": false,
    "code": 403,
    "message": "无权操作该任务"
}

任务已结束:

{
    "success": false,
    "code": 500,
    "message": "任务已结束，不能停止"
}

注意事项

• 请区分主任务与子任务状态：主任务 processing 表示任务整体执行中，此时可以调用停止接口；子任务 assigned 表示已分配并运行中，这类子任务无法被立即中断。

• 停止的实际拦截范围：只有 pending（未分配）、failed（执行失败）的子任务会被拦截；assigned 状态（此为正在节点执行的任务，一般不会特别多）的子任务无法被中断，后续将执行完成并计费。

• 停止是不可逆操作，任务一旦进入 stopped 状态将无法恢复继续执行，如需重新监控请重新提交批量监控任务。

---

获取任务结果

接口地址: GET /task/result/{taskId}

接口描述: 获取批量任务的完整结果信息，包含所有子任务的详细数据

需要认证: 是

请求参数

路径参数:

响应结果

成功响应（示例已精简，实际返回包含完整answerContent）:

{
    "success": true,
    "code": 200,
    "message": "操作成功",
    "data": {
        "taskId": "5a85cdd0ed9249cfb69daaeca2b91a09",
        "consumerTaskId": "consumerTask202606300001",
        "status": "completed",
        "totalItems": 2,
        "completedItems": 2,
        "failedItems": 0,
        "subTaskList": [
            {
                "subTaskId": "1037393",
                "platform": "yuanbao",
                "mode": "search",
                "prompt": "目前市场上销量较高的手机品牌有哪些",
                "status": "completed",
                "time": 1781080983000,
                "pageScreenshot": "https://{IMAGE_DOMAIN}/screenshots/2026/06/10/504ed036c9cb446bb941ca35ee59568f_yuanbao_20260610_164249.png",
                "answerContent": "结合2026年上半年的市场数据，目前市面上销量最稳、关注度最高的品牌主要集中在以下几个阵营， ...",
                "referenceList": [
                    {
                        "index": 1,
                        "title": "华为Mate80累计销量近650万!可只及iPhone 17国内两成",
                        "url": "https://new.qq.com/rain/a/20260610A03XXQ00",
                        "summary": "大约是iPhone 17国内销售的两成,即使算上Pura80､Pura X2等机型,华为旗舰手机销量...",
                        "publishTime": "2026-06-10",
                        "site": "腾讯网",
                        "icon": "icons/ddb169535e49d0bdbee77ba42dd570ce.ico"
                    }
                ],
                "citationList": [
                    {
                        "index": 16,
                        "title": "2026手机销量榜大结局:苹果华为高端对决,荣耀逆袭千元市场",
                        "url": "https://post.smzdm.com/p/aggk9god",
                        "publishTime": "2026-03-17",
                        "site": "什么值得买",
                        "icon": "icons/8f67abc6859d51a0b9922b3de42312ba.ico"
                    }
                ],
                "reasoningProcess": {
                    "summary": "",
                    "content": "用户想了解市场销量较高的手机品牌，我会搜索最新手机市场销量数据，以此给出准确答复。"
                },
                "recommendedQuestions": [
                    "哪些手机品牌口碑最好？",
                    "2026年手机销量排行榜前十名有哪些变化？",
                    "苹果和华为在高端市场的具体差异是什么？"
                ],
                "searchKeywords": [
                    "手机品牌销量排行 2026",
                    "高端手机市场品牌对比"
                ],
                "mediaContent": [],
                "videoList": [
                    {
                        "videoPlatform": "douyin",
                        "videoId": "7480000000000000000",
                        "title": "2026上半年手机销量榜盘点：华为、苹果、小米谁更能打",
                        "url": "https://www.douyin.com/video/7480000000000000000",
                        "cover": "https://p3.douyinpic.com/aweme/cover_xxx.jpeg",
                        "author": "科技数码评测",
                        "duration": "05:23",
                        "position": 1
                    }
                ],
                "goods": [
                    {
                        "title": "小米 17 Pro 12GB+256GB 白色",
                        "url": "https://item.jd.com/100278751428.html",
                        "thumbnail": "https://img14.360buyimg.com/n1/jfs/t1/397871/33/15002/20525/00ae1e01e071a1e9.jpg",
                        "price": "4999",
                        "priceUnit": "¥",
                        "mall": "京东",
                        "mallPlatform": "jd",
                        "mallProductId": "100278751428",
                        "position": 1
                    }
                ],
                "errorMessage": null,
                "proxyIp": null,
                "amount": 0.234,
                "mentionPosition": 2,
                "mentionContext": "在国内高端市场极具号召力，影像与鸿蒙生态体验出色，是商务人士的首选之一。",
                "sentiment": "positive",
                "competitorRankings": [
                    {
                        "name": "苹果",
                        "rank": 1
                    },
                    {
                        "name": "小米",
                        "rank": 6
                    }
                ],
                "allRankings": [
                    {
                        "name": "苹果",
                        "rank": 1
                    },
                    {
                        "name": "华为",
                        "rank": 2
                    },
                    {
                        "name": "小米",
                        "rank": 6
                    }
                ],
                "categoryRanking": {
                    "categoryName": "高端手机品牌",
                    "rank": 2,
                    "allRankings": [
                        {
                            "name": "苹果",
                            "rank": 1
                        },
                        {
                            "name": "华为",
                            "rank": 2
                        },
                        {
                            "name": "小米",
                            "rank": 3
                        }
                    ]
                },
                "keywordEvaluations": [
                    {
                        "keyword": "影像体验出色",
                        "nature": "positive",
                        "context": "在国内高端市场极具号召力，影像与鸿蒙生态体验出色，是商务人士的首选之一。"
                    },
                    {
                        "keyword": "商务人士首选",
                        "nature": "positive",
                        "context": "在国内高端市场极具号召力，影像与鸿蒙生态体验出色，是商务人士的首选之一。"
                    }
                ]
            }
        ]
    }
}

响应字段说明:

---

获取子任务结果

接口地址: GET /task/result/{taskId}/{subTaskId}

接口描述: 获取指定子任务的详细监控结果

需要认证: 是

请求参数

路径参数:

响应结果

成功响应（由于内容过长，answerContent已精简）:

{
    "success": true,
    "code": 200,
    "message": "操作成功",
    "data": {
        "subTaskId": "1037393",
        "platform": "yuanbao",
        "mode": "search",
        "prompt": "目前市场上销量较高的手机品牌有哪些",
        "status": "completed",
        "time": 1781080983000,
        "pageScreenshot": "https://{IMAGE_DOMAIN}/screenshots/2026/06/10/504ed036c9cb446bb941ca35ee59568f_yuanbao_20260610_164249.png",
        "answerContent": "结合2026年上半年的市场数据，目前市面上销量最稳、关注度最高的品牌主要集中在以下几个阵营，你可以根据自己的预算和偏好对号入座：...",
        "referenceList": [
            {
                "index": 1,
                "title": "华为Mate80累计销量近650万!可只及iPhone 17国内两成",
                "url": "https://new.qq.com/rain/a/20260610A03XXQ00",
                "summary": "大约是iPhone 17国内销售的两成,即使算上Pura80､Pura X2等机型,华为旗舰手机销量...",
                "publishTime": "2026-06-10",
                "site": "腾讯网",
                "icon": "icons/ddb169535e49d0bdbee77ba42dd570ce.ico"
            }
        ],
        "citationList": [
            {
                "index": 16,
                "title": "2026手机销量榜大结局:苹果华为高端对决,荣耀逆袭千元市场",
                "url": "https://post.smzdm.com/p/aggk9god",
                "publishTime": "2026-03-17",
                "site": "什么值得买",
                "icon": "icons/8f67abc6859d51a0b9922b3de42312ba.ico"
            }
        ],
        "reasoningProcess": {
            "summary": "",
            "content": "用户想了解市场销量较高的手机品牌，我会搜索最新手机市场销量数据，以此给出准确答复。"
        },
        "recommendedQuestions": [
            "哪些手机品牌口碑最好？",
            "2026年手机销量排行榜前十名有哪些变化？",
            "苹果和华为在高端市场的具体差异是什么？"
        ],
        "searchKeywords": [
            "手机品牌销量排行 2026",
            "高端手机市场品牌对比"
        ],
        "mediaContent": [],
        "videoList": [
            {
                "videoPlatform": "douyin",
                "videoId": "7480000000000000000",
                "title": "2026上半年手机销量榜盘点：华为、苹果、小米谁更能打",
                "url": "https://www.douyin.com/video/7480000000000000000",
                "cover": "https://p3.douyinpic.com/aweme/cover_xxx.jpeg",
                "author": "科技数码评测",
                "duration": "05:23",
                "position": 1
            }
        ],
        "goods": [
            {
                "title": "小米 17 Pro 12GB+256GB 白色",
                "url": "https://item.jd.com/100278751428.html",
                "thumbnail": "https://img14.360buyimg.com/n1/jfs/t1/397871/33/15002/20525/00ae1e01e071a1e9.jpg",
                "price": "4999",
                "priceUnit": "¥",
                "mall": "京东",
                "mallPlatform": "jd",
                "mallProductId": "100278751428",
                "position": 1
            }
        ],
        "errorMessage": null,
        "proxyIp": null,
        "amount": 0.234,
        "mentionPosition": 2,
        "mentionContext": "在国内高端市场极具号召力，影像与鸿蒙生态体验出色，是商务人士的首选之一。",
        "sentiment": "positive",
        "competitorRankings": [
            {
                "name": "苹果",
                "rank": 1
            },
            {
                "name": "小米",
                "rank": 6
            }
        ],
        "allRankings": [
            {
                "name": "苹果",
                "rank": 1
            },
            {
                "name": "华为",
                "rank": 2
            },
            {
                "name": "小米",
                "rank": 6
            }
        ],
        "categoryRanking": {
            "categoryName": "高端手机品牌",
            "rank": 2,
            "allRankings": [
                {
                    "name": "苹果",
                    "rank": 1
                },
                {
                    "name": "华为",
                    "rank": 2
                },
                {
                    "name": "小米",
                    "rank": 3
                }
            ]
        },
        "keywordEvaluations": [
            {
                "keyword": "影像体验出色",
                "nature": "positive",
                "context": "在国内高端市场极具号召力，影像与鸿蒙生态体验出色，是商务人士的首选之一。"
            },
            {
                "keyword": "商务人士首选",
                "nature": "positive",
                "context": "在国内高端市场极具号召力，影像与鸿蒙生态体验出色，是商务人士的首选之一。"
            }
        ]
    }
}

响应字段说明:

子任务状态值:

子任务完成条件

子任务状态为 completed 需要满足：

• AI 回答内容生成完成

• 如需截图（screenshot=1 或 screenshot=2），截图已完成

• 如有引用来源，信源解析已完成

---

获取任务列表

接口地址: GET /task/list

接口描述: 获取用户的任务列表，支持分页和状态过滤

需要认证: 是

请求参数

Query 参数:

响应结果

成功响应:

{
    "success": true,
    "code": 200,
    "message": "操作成功",
    "data": {
        "total": 6012,
        "page": 1,
        "size": 10,
        "tasks": [
            {
                "taskId": "05c517d143cd4f229786d294942b5a96",
                "consumerTaskId": "consumerTask202606300001",
                "prompts": [
                    "目前市场上销量较高的手机品牌有哪些"
                ],
                "platforms": [
                    {
                        "mode": "reasoning_search",
                        "platform": "doubao",
                        "screenshot": 1
                    }
                ],
                "monitorKeyword": "华为",
                "monitorKeywordAliases": [
                    "HUAWEI",
                    "华为手机"
                ],
                "competitors": [
                    {
                        "name": "小米",
                        "aliases": [
                            "Xiaomi",
                            "小米手机"
                        ]
                    },
                    {
                        "name": "苹果",
                        "aliases": [
                            "Apple",
                            "iPhone"
                        ]
                    }
                ],
                "status": "processing",
                "totalItems": 1,
                "completedItems": 0,
                "failedItems": 0,
                "createdAt": 1781091896000,
                "completedAt": null
            },
            {
                "taskId": "9aaa0a04211144c385d1186e76f85df3",
                "consumerTaskId": null,
                "prompts": [
                    "请帮我搜索最新款 iPhone型号，以及 iOS 版本",
                    "请帮我推荐一款智能手机"
                ],
                "platforms": [
                    {
                        "mode": "reasoning_search",
                        "platform": "doubao",
                        "screenshot": 0
                    },
                    {
                        "mode": "search",
                        "platform": "yuanbao",
                        "screenshot": 0
                    }
                ],
                "monitorKeyword": null,
                "monitorKeywordAliases": null,
                "competitors": null,
                "status": "completed",
                "totalItems": 4,
                "completedItems": 4,
                "failedItems": 0,
                "createdAt": 1781084231000,
                "completedAt": 1781085438000
            }
        ]
    }
}

响应字段说明:

---

Callback 回调

任务完成后，系统会主动将结果推送到您配置的回调地址，无需轮询查询。

回调地址

回调地址分两种：全局 callback（账号级别，通过接口设置）和任务级 callback（任务级别，提交任务时指定）。

两者同时存在时，任务级 callback 优先。均未配置时任务完成后不触发回调。

提交任务的响应中会返回 callbackUrl 字段，反映本次任务实际生效的地址。

管理全局回调地址

查询 callback

GET /api/business/monitor/task/callback-url   需要认证

{
    "success": true,
    "code": 200,
    "message": "操作成功",
    "data": "https://your-domain.com/callback"
}

data 为当前配置的地址字符串，未配置时返回 null。

修改 callback

PUT /api/business/monitor/task/callback-url   需要认证

请求体：

{
    "callbackUrl": "https://your-domain.com/callback"
}

响应：

{
    "success": true,
    "code": 200,
    "message": "回调地址更新成功",
    "data": null
}

回调类型

默认回调

未做任何特殊配置时，系统使用默认回调。任务完成后，系统向您的回调地址发送一次 HTTP POST 请求，Content-Type 为 application/json。

请求体结构：

{
    "taskId": "task_abc123",
    "consumerTaskId": "consumerTask202606300001",
    "userId": 10001,
    "timestamp": 1712640000000,
    "status": "completed",
    "totalItems": 10,
    "completedItems": 9,
    "failedItems": 1,
    "subTaskList": [
        {
            "subTaskId": "sub_001",
            "platform": "deepseek",
            "mode": "search",
            "status": "completed",
            "...": "..."
        }
    ]
}

响应约定：

您的服务返回 HTTP 2xx 状态码即视为回调成功。非 2xx 响应或网络超时时，系统会按退避策略自动重试。

自定义回调

如您有以下需求，可联系我们进行对接，开启自定义回调：

• 请求体需要特定签名或加密（如 HMAC-SHA256 签名验证、AES 加密）

• 需要对接第三方平台接口（如需先获取 Access Token 再推送数据）

• 回调数据格式与默认格式不兼容，需要字段映射或定制

联系对接自定义回调由我们在服务端配置，您无法通过 API 自行切换。如需开通，请联系对接人员说明您的签名算法或接口规范。

回调失败处理

建议在您的回调接口中实现幂等处理，以应对重试场景（同一 taskId 可能收到多次推送）。

如需主动查询任务结果，可使用获取任务结果作为补偿。

---

获取可用区域列表

在提交批量任务时，可以通过 regionCode 参数指定节点使用的国内或海外区域。这样可以确保节点从指定地区发起请求，获取地域化的数据结果。

国内区域

接口说明

接口地址: GET /api/business/eip-edge/ports/city-info

接口描述: 查询所有可用的区域信息，用于获取 regionCode 参数的可选值

需要认证: 否（公开接口）

请求参数

Query 参数:

响应结果

成功响应:

{
  "success": true,
  "code": 200,
  "message": "操作成功",
  "data": [
    {
      "province": "河南省",
      "regionCode": ["410000"]
    },
    {
      "province": "陕西省",
      "regionCode": ["610100"]
    }
  ]
}

响应字段说明:

使用流程

# 步骤1: 获取可用区域列表
curl -X GET "https://{API_DOMAIN}/api/business/eip-edge/ports/city-info"

# 步骤2: 从响应中提取 regionCode
# 例如获取到：河南省-410000

# 步骤3: 提交任务时指定 regionCode
curl -X POST "https://{API_DOMAIN}/api/business/monitor/task/batch/shared" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompts": ["人工智能发展趋势"],
    "platforms": [{"platform": "deepseek", "mode": "search"}],
    "regionCode": ["410000"]
  }'

注意事项

• regionCode 格式： 必须是有效的行政区划代码，可以通过本接口获取

• 单区域限制： 当前仅支持指定 1 个 regionCode（数组长度必须为 1）

• 未指定时的行为： 如果不传 regionCode 参数，节点会使用默认策略

• 代码有效性： regionCode 必须是当前可用的端口对应的区域代码，否则可能导致任务执行失败

海外国家/地区

在提交批量任务时，可以通过 regionCode 参数指定节点使用的海外国家或地区。以下接口用于获取当前支持的海外国家/地区及其区域代码。

接口说明

接口地址: GET /api/business/eip-edge/regions/overseas

接口描述: 查询系统已配置的海外国家/地区及其 regionCode

需要认证: 否（公开接口）

请求参数

Query 参数:

响应结果

成功响应:

{
  "success": true,
  "code": 200,
  "message": "操作成功",
  "data": [
    {
      "name": "美国",
      "regionCode": ["138"]
    },
    {
      "name": "日本",
      "regionCode": ["169"]
    },
    {
      "name": "香港",
      "regionCode": ["223"]
    },
    {
      "name": "新加坡",
      "regionCode": ["224"]
    }
  ]
}

响应字段说明:

请求示例

curl -X GET "https://{API_DOMAIN}/api/business/eip-edge/regions/overseas" \
  -H "Accept: application/json"

使用示例

以下示例演示如何使用美国节点发起请求：

curl -X POST "https://{API_DOMAIN}/api/business/monitor/task/batch/shared" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompts": ["人工智能发展趋势"],
    "platforms": [{"platform": "chatgpt", "mode": "search"}],
    "regionCode": ["138"]
  }'

注意事项

• 单区域限制： 当前提交任务仅支持指定 1 个 regionCode（数组长度必须为 1）

• 国家/地区范围： 当前支持美国、日本、香港和新加坡，以接口实际返回结果为准

• 未指定时的行为： 如果不传 regionCode，节点会使用默认策略

---

费用对账

费用对账接口用于查询当前账号的消费汇总、消费明细和当前余额。目前仅支持统计 API 项目产生的消费记录，后续将支持非 API 项目，以及充值、赠送、解冻等非消费流水。

需要认证: 是

费用汇总查询

接口地址: POST /api/reconciliation/summary

接口描述: 查询指定日期范围内 API 项目的消费总金额和消费次数。返回结果会包含本次请求参数，便于客户侧对账落库。

请求参数

Body 参数:

请求限制:

• startDate 不能晚于 endDate

• 单次查询日期范围最多支持 31 天

• 目前仅支持统计 API 项目产生的消费记录，后续将支持非 API 项目及非消费流水

请求示例

{
    "startDate": "2026-06-01",
    "endDate": "2026-06-30",
    "aiModel": "doubao",
    "taskId": "e619e12d90d644ae9e64ea26472df007"
}

curl 示例

curl -X POST "https://{API_DOMAIN}/api/reconciliation/summary" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "startDate": "2026-06-01",
    "endDate": "2026-06-30",
    "aiModel": "doubao",
    "taskId": "e619e12d90d644ae9e64ea26472df007"
  }'

响应结果

成功响应:

{
    "success": true,
    "code": 200,
    "message": "操作成功",
    "data": {
        "startDate": "2026-06-01",
        "endDate": "2026-06-30",
        "aiModel": "doubao",
        "taskId": "e619e12d90d644ae9e64ea26472df007",
        "totalCount": 1280,
        "totalConsume": "463.84"
    }
}

响应字段说明:

费用明细查询

接口地址: POST /api/reconciliation/records

接口描述: 分页查询指定日期范围内 API 项目的消费明细。接口使用传统分页，明细按交易时间倒序返回。

请求参数

Body 参数:

请求限制:

• startDate 不能晚于 endDate

• 单次查询日期范围最多支持 31 天

• pageSize 最大支持 1000

• 分页查询深度超过限制时会返回错误，请缩小时间范围或增加筛选条件后重试

• 目前仅支持统计 API 项目产生的消费记录，后续将支持非 API 项目及非消费流水

请求示例

{
    "startDate": "2026-06-01",
    "endDate": "2026-06-30",
    "aiModel": "doubao",
    "taskId": "e619e12d90d644ae9e64ea26472df007",
    "pageNum": 1,
    "pageSize": 100
}

curl 示例

curl -X POST "https://{API_DOMAIN}/api/reconciliation/records" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "startDate": "2026-06-01",
    "endDate": "2026-06-30",
    "aiModel": "doubao",
    "taskId": "e619e12d90d644ae9e64ea26472df007",
    "pageNum": 1,
    "pageSize": 100
  }'

响应结果

成功响应:

{
    "success": true,
    "code": 200,
    "message": "操作成功",
    "data": {
        "records": [
            {
                "id": 10001,
                "taskId": "e619e12d90d644ae9e64ea26472df007",
                "subTaskId": 20001,
                "taskCreatedTime": 1781917200000,
                "taskCompletedTime": 1781919012000,
                "transactionTime": 1781920812000,
                "amount": "0.234",
                "description": "豆包（网页版）+深度思考",
                "aiModel": "doubao",
                "aiModelText": "豆包（网页版）",
                "question": "目前市场上销量较高的手机品牌有哪些"
            }
        ],
        "total": 1280,
        "currentPage": 1,
        "pageSize": 100,
        "totalPages": 13
    }
}

响应字段说明:

当前余额查询

接口地址: GET /api/reconciliation/balance

接口描述: 查询当前账号可用余额。

请求参数

无。

curl 示例

curl -X GET "https://{API_DOMAIN}/api/reconciliation/balance" \
  -H "Authorization: Bearer YOUR_TOKEN"

响应结果

成功响应:

{
    "success": true,
    "code": 200,
    "message": "操作成功",
    "data": {
        "currentBalance": "1288.66"
    }
}

响应字段说明:

错误响应

{
    "success": false,
    "code": 400,
    "message": "单次对账查询最多支持31天",
    "data": null
}

常见错误：

---

查询支持的模型列表

接口地址: GET /api/business/system/models

接口描述: 查询当前支持的 AI 模型列表，可用于提交任务前动态获取可选平台。

需要认证: 否

请求参数

无请求参数。

curl 示例

curl -X GET "https://{API_DOMAIN}/api/business/system/models"

响应结果

成功响应:

{
    "success": true,
    "code": 200,
    "message": "操作成功",
    "data": [
        {
            "modelCode": "doubao",
            "modelName": "豆包",
            "description": "字节跳动的豆包大模型",
            "clientType": "web"
        },
        {
            "modelCode": "doubao_mobile",
            "modelName": "豆包移动端",
            "description": "豆包移动端 App",
            "clientType": "mobile"
        }
    ]
}

响应字段说明:

使用说明

• 接口返回值会随后台模型配置动态变化，建议客户端以该接口返回的 modelCode 作为可选平台来源。

---

错误处理

通用错误格式

{
  "success": false,
  "code": 300001,
  "message": "请求参数错误",
  "data": null
}

常见错误码

Token 认证错误

当 Token 无效、过期或未提供时，拦截器会直接返回错误响应（HTTP 200）：

{
  "success": false,
  "code": 500,
  "message": "Token失效",
  "data": null
}

备注认证失败返回的 HTTP 状态码仍为 200，通过响应体的 success 和 code 字段判断请求结果。

错误处理建议

• 请妥善处理各种错误情况

• 特别注意网络异常和认证失败的处理

• 子任务失败时，errorMessage 字段会包含错误详情

• Token 过期后需要重新获取

---

使用指南

完整工作流程

# 步骤1: 提交批量监控任务
curl -X POST "https://{API_DOMAIN}/api/business/monitor/task/batch/shared" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompts": ["人工智能发展趋势", "机器学习应用"],
    "platforms": [
      {"platform": "deepseek", "mode": "search", "screenshot": 1}
    ]
  }'

# 步骤2: 查询任务状态
curl -X GET "https://{API_DOMAIN}/api/business/monitor/task/status/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_TOKEN"

# 步骤3: 停止未结束的任务（可选）
curl -X PUT "https://{API_DOMAIN}/api/business/monitor/task/550e8400-e29b-41d4-a716-446655440000/stop" \
  -H "Authorization: Bearer YOUR_TOKEN"

# 步骤4: 获取完整结果
curl -X GET "https://{API_DOMAIN}/api/business/monitor/task/result/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_TOKEN"

# 步骤5: 获取单个子任务结果
curl -X GET "https://{API_DOMAIN}/api/business/monitor/task/result/550e8400-e29b-41d4-a716-446655440000/660e8400-e29b-41d4-a716-446655440001" \
  -H "Authorization: Bearer YOUR_TOKEN"

# 步骤6: 获取任务列表
curl -X GET "https://{API_DOMAIN}/api/business/monitor/task/list?page=1&size=10&status=completed" \
  -H "Authorization: Bearer YOUR_TOKEN"

# 步骤7: 配置默认回调地址（可选）
curl -X PUT "https://{API_DOMAIN}/api/business/monitor/task/callback-url" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"callbackUrl":"https://your-domain.com/callback"}'

注意事项

认证与权限

• 所有接口都需要有效的认证 Token

• Token 通过 Authorization: Bearer 头传递

• Token 过期后需要重新获取

任务执行流程

• 任务提交后初始状态为 pending，系统异步处理

• 建议每 5-10 秒轮询一次状态接口，避免过于频繁的请求

• 当 status 为 completed、partial_completed、failed 或 stopped 时，可以获取最终结果

数据保留

• 任务结果数据会保留一定时间

• 建议及时获取和备份重要数据

Callback 回调（可选）

系统支持在任务完成后主动推送结果，无需轮询。

• 全局 callback：通过接口预先设置账号级别的默认地址

• 任务级 callback：提交任务时通过 callbackUrl 字段临时指定，仅对该次任务生效

• 两者均未配置时，任务完成后不触发推送

完整的触发条件、请求格式、重试策略及自定义回调说明，详见 Callback 回调。

---

更新日志