首页
学习
活动
专区
圈层
工具
发布
社区首页 >专栏 >数据鱼API接口详解:标题评分与词数统计(headline-analyzer)

数据鱼API接口详解:标题评分与词数统计(headline-analyzer)

原创
作者头像
用户12862874
发布于 2026-11-20 21:58:04
发布于 2026-11-20 21:58:04
110
举报

接口简介

「标题分析」是数据鱼API平台提供的英文标题启发式评分接口,Base 路径 /api/headline-analyzer,共 3 个端点。它接收一条标题文本,按空格切分统计词数,再用几条固定规则给出 0 到 100 的分数与改进建议,用于内容发布前的快速自查。

这个接口的定位是规则打分,不是语义模型。评分只考虑三个信号:词数是否落在 6 到 9 个词之间、是否包含 How to、Why、Best、Top 这类引导词、是否以问号或感叹号结尾。基础分为 50,命中规则逐项加分,最终不超过 100。它不理解标题的含义,也不判断事实准确性。

由于规则基于空格分词与英文正则,接口对英文标题有效,对中文标题几乎不起作用:中文句子没有空格,整条标题会被计为 1 个词,引导词正则也不会命中。接入前应确认内容语言,中文标题更适合做字数与标点检查,而不是依赖本接口的总分。

端点总览

方法

路径

说明

鉴权

GET

/api/headline-analyzer/ping

健康检查,返回版本号与服务器时间

免鉴权

GET

/api/headline-analyzer

根路径探测端点,返回空数组,不承载业务数据

需要 Key

GET

/api/headline-analyzer/analyze

标题分析主端点,参数 headline,返回评分与建议

需要 Key

通用约定

鉴权使用全站统一 Key,通过 X-API-Key 请求头或 api_key 查询参数传递,缺失返回 4011,无效返回 4013;ping 免鉴权,可直接用于探活。文档同时说明 GET 与 POST 均可,POST 支持 JSON 体或表单,参数名与查询参数一致。

响应结构为 {"code":0,"msg":"success","data":{...}}。业务错误码包括 4001 缺少必填参数、4002 参数格式非法、4003 取值不在支持列表、4004 查询目标未收录、4050 方法不允许;4011、4013、4040 与全站一致,5000、5001 为服务内部错误。数据鱼API对参数错误与鉴权错误分开编码,便于客户端区分重试与改参。

核心端点详解

标题分析

对单条标题执行规则评分,返回分数、词数与建议。这是接口唯一的业务端点。

参数

类型

必填

默认

说明

headline

string

是(业务上)

空串

待分析的标题文本;省略时按空串计算,不报错

响应按文档示例包含四个字段:headline 原样回显、overall_score 总分(0-100)、word_count 词数、power_words_found 命中的引导词数量,以及 suggestion 一句英文建议。分数低于 80 时建议为 Add power words 或 Check length 一类提示,达到 80 及以上返回 Looks good!。

代码语言:javascript
复制
GET /api/headline-analyzer/analyze?headline=How to choose a laptop

评分口径可以还原为四条:基础分 50;词数大于 5 且小于 10 时加 20;命中 How to、Why、Best、Top 任一引导词加 20;包含问号或感叹号加 10;总分最高不超过 100。因此一条 6 到 9 个词、带引导词、以问号结尾的标题可以直接拿到满分。

根路径与探活

根路径端点不接受参数,返回 data: [],没有业务含义,可用于确认路由与鉴权链路是否正常。ping 端点免鉴权,返回 {"code":0,"msg":"pong","data":{"version":"1.0.0","time":"..."}},其中 time 为服务器当前时间,适合做定时探活与时钟偏差检查。

代码语言:javascript
复制
GET /api/headline-analyzer/ping
GET /api/headline-analyzer

这两个端点不参与评分逻辑,接入时无需在业务链路中调用,放在部署检查脚本里即可。

数据与限制

  • 端点数量:3 个,业务端点仅 analyze 一个。
  • 评分范围:0 到 100,基础分 50,单次最多加 50 分。
  • 词数规则:仅当词数大于 5 且小于 10 时加分,5 个词与 10 个词都不在加分区间。
  • 引导词:How to、Why、Best、Top,大小写不敏感,按子串匹配。
  • 语言范围:按空格分词,面向英文标题;中文标题整条计为 1 个词。
  • 标点规则:标题中出现 ? 或 ! 即加 10 分,不区分位置。
  • 单次请求只处理一条标题,不提供批量参数。
  • 缓存与时效:接口不缓存结果,同一标题每次返回相同分数;文档未给出调用频率上限。

典型使用场景

  • 内容运营初筛:编辑写完英文标题后调用一次,低于 60 分时按建议补引导词或调整词数。
  • CMS 发布前提示:在保存草稿的流程里加一个非阻断式提示,展示分数与建议,不强制拦截。
  • 标题 A/B 预评估:对多个候选标题批量调用(客户端循环),按分数排序后再进入人工评审。
  • 教学与演示:用固定规则解释标题写作中的长度、情绪词与标点习惯,比黑盒模型更易讲解。

注意事项

  • 文档示例中 headline=1 返回 word_count: 0,但实现按空格切分会把单个词计为 1。单词标题的词数结果请以实际响应为准,不要依赖示例值。
  • 响应字段名在文档与实现之间存在差异:文档示例为 overall_score、power_words_found、suggestion,实现返回 score 与 suggestions 数组。对接时先抓一次真实响应再定解析字段,并在代码里做兼容。
  • 中文标题因缺少空格只会得到 1 个词,且不会命中英文引导词,分数通常停在 50 或 60,不能据此判断中文标题质量。
  • 评分是纯规则计算,不理解语义、不查重、不检测夸张或违规表述;高分只代表命中规则,不代表标题合格。
  • headline 省略时不会返回 4001,而是按空串计算并返回低分。若业务要求必填,应由调用方自行校验空值。
  • 规则与阈值属于实现细节,数据鱼API后续调整规则时可能不另行通知,建议只把分数用于排序参考,不写入硬性业务阈值。

原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。

如有侵权,请联系 cloudcommunity@tencent.com 删除。

目录
  • 接口简介
  • 端点总览
  • 通用约定
  • 核心端点详解
    • 标题分析
    • 根路径与探活
  • 数据与限制
  • 典型使用场景
  • 注意事项
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档