# 公文校对 API 文档

# 接口说明

公文校对能够对文本内容进行文字标点差错、知识性差错、内容导向风险识别三大类型27种错误分类的审核与校对，具体如下：
1.文字标点差错校对：错别字、词、多字错误、少字错误、语义重复、语序错误、句式杂糅、标点符号差错、量词和单位差错、数字差错、句子查重、序号检查。
2.知识性差错校对：地理名词、机构名称、专有名词及术语、常识差错、媒体报道禁用词和慎用词等。

购买请点击API套餐购买 (opens new window)、APPID获取请点击API使用控制台 (opens new window)、交流讨论请点击讯飞开放平台社区 (opens new window)

# 接口Demo

部分开发语言Demo如下，其他开发语言请参照文档进行开发，欢迎大家到讯飞开放平台社区 (opens new window)交流集成经验。

公文校对API Demo java语言 (opens new window)
公文校对API Demo python语言 (opens new window)

# 接口要求

内容	说明
传输方式	http[s] (为提高安全性，强烈推荐https)
请求地址	https://cn-huadong-1.xf-yun.com/v1/private/s37b42a45 注：服务器IP不固定，为保证您的接口稳定，请勿通过指定IP的方式调用接口，使用域名方式调用
Content-Type	application/json;charset=UTF-8
接口鉴权	签名机制，详情请参照下方接口鉴权
字符编码	UTF-8
响应格式	统一采用JSON格式
开发语言	任意，只要可以向讯飞云服务发起HTTP请求的均可
适用范围	任意操作系统，但因不支持跨域不适用于浏览器
文本长度	不得超过220000个字符，汉字、英文字母、标点都算做一个字符

# 接口鉴权

# 1、鉴权参数列表

所有鉴权参数均放在url地址栏。http最终请求示例url如下：

https://cn-huadong-1.xf-yun.com/v1/private/s37b42a45?authorization=YXBpX2tleT0iOTEyMDVhZmUwZDE3ZTM4YzYxYmUzNWZjYTM0NjUwM2MiLCBhbGdvcml0aG09ImhtYWMtc2hhMjU2IiwgaGVhZGVycz0iaG9zdCBkYXRlIHJlcXVlc3QtbGluZSIsIHNpZ25hdHVyZT0iejhVZWhEYmZ6K2N3QU9hdEJQV25iMHZYNTZnZml3MnZlcnZtdGgvTmI0ST0i&date=Mon%2C%2028%20Aug%202023%2010%3A05%3A35%20GMT&host=cn-huadong-1.xf-yun.com

参数名	类型	必传	描述
host	String	是	请求主机：cn-huadong-1.xf-yun.com
date	String	是	当前时间戳，RFC1123格式("EEE, dd MMM yyyy HH:mm:ss z") 示例：Mon, 28 Aug 2023 10:05:35 GMT
authorization	String	是	使用base64编码的签名相关信息(签名基于hamc-sha256计算) 具体参考下方详细生成规则

# 2、第一步date生成规则

date必须是UTC+0或GMT时区，RFC1123格式(Wed, 11 Nov 2020 06:24:43 GMT)。 服务端会对date进行时钟偏移检查，最大允许300秒的偏差，超出偏差的请求都将被拒绝。

# 3、第二步signature原始值示例（signature_origin）

host: cn-huadong-1.xf-yun.com
date: Mon, 28 Aug 2023 10:05:35 GMT
POST /v1/private/s37b42a45 HTTP/1.1

# 4、第三步signature获取最终值

（1）使用hmac-sha256算法结合apiSecret对signature_origin签名，获得签名后的摘要signature_sha。

signature_sha=hmac-sha256(signature_origin,$apiSecret)

（2）使用base64编码对signature_sha进行编码获得最终的signature

signature=base64(signature_sha)
基于第二步signature_origin、apiSecret以ff446b96b01252f80331ae6e4c64984a生成的最终结果示例：
z8UehDbfz+cwAOatBPWnb0vX56gfiw2vervmth/Nb4I=

# 5、第四步authorization的base64前原始值示例（authorization_origin）

api_key="$api_key",algorithm="hmac-sha256",headers="host date request-line",signature="$signature"

# 6、第五步authorization获取最终值

authorization = base64(authorization_origin)
基于authorization_origin进行base64生成的最终示例：
YXBpX2tleT0iOTEyMDVhZmUwZDE3ZTM4YzYxYmUzNWZjYTM0NjUwM2MiLCBhbGdvcml0aG09ImhtYWMtc2hhMjU2IiwgaGVhZGVycz0iaG9zdCBkYXRlIHJlcXVlc3QtbGluZSIsIHNpZ25hdHVyZT0iejhVZWhEYmZ6K2N3QU9hdEJQV25iMHZYNTZnZml3MnZlcnZtdGgvTmI0ST0i

# 请求与返回示例

在调用业务接口时，均在 Http RequestBody中配置以下参数，请求与返回数据均为json字符串，示例如下。

# 1、请求json示例

{
  "header": {
    "app_id": "your_appid",
    "status": 3
  },
  "parameter": {
    "midu_correct": {
      "output_result": {
        "encoding": "utf8",
        "compress": "raw",
        "format": "json"
      }
    }
  },
  "payload": {
    "text": {
      "encoding": "utf8",
      "compress": "raw",
      "format": "plain",
      "status": 3,
      "text": "56ys5LqM5Liq55m+5bm055uu5qCH"
    }
  }
}

# 2、返回json示例

{
  "header": {
    "code": 0,
    "message": "success",
    "sid": "ase000e2b1b@hu18a3f00e65d1323882"
  },
  "payload": {
    "output_result": {
      "compress": "raw",
      "encoding": "utf8",
      "format": "json",
      "seq": "0",
      "status": "3",
      "text": "eyJjb2RlIjogMjAwLCAibX..."
    }
  }
}

根据上面返回结果，text字段base64解码后json示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "checklist": [
      {
        "wordHtml": "第二个百年目标",
        "explanation": "推荐使用更常用的公文规范表述",
        "type": {
          "id": 8,
          "belongId": 8,
          "name": "xxx",
          "desc": "xxx"
        },
        "word": "第二个百年目标",
        "action": {
          "id": 2
        },
        "htmlWords": [
          {
            "word": "第二个百年目标",
            "position": 0
          }
        ],
        "suggest": [
          "第二个百年奋斗目标"
        ],
        "context": "第二个百年目标",
        "position": 0,
        "length": 7,
        "source": 2,
        "um_error_level": 1
      }
    ]
  },
  "umeiTransactionId": "0e49fe88029aeb10"
}

# 参数说明

# 1、请求参数说明

参数名	类型	必传	描述
header	object	是	用于上传平台参数
header.app_id	string	是	在平台申请的appid信息
header.status	int	是	请求状态，取值范围为：3（一次传完）
parameter	object	是	用于上传服务特性参数
parameter.midu_correct	object	是	服务名称
parameter.midu_correct.output_result	object	是	用于上传响应数据参数
parameter.midu_correct.output_result.encoding	string	否	文本编码，可选值：utf8（默认值）
parameter.midu_correct.output_result.compress	string	否	文本压缩格式，可选值：raw（默认值）
parameter.midu_correct.output_result.format	string	否	文本格式，可选值：json（默认值）
payload	object	是	用于上传请求数据
payload.text	object	是	用于上传文本数据
payload.text.encoding	string	否	文本编码，可选值：utf8（默认值）
payload.text.compress	string	否	文本压缩格式，可选值：raw（默认值）
payload.text.format	string	否	文本格式，可选值：json（默认值）
payload.text.text	string	是	文本数据，不得超过220000个字符
payload.text.status	int	否	上传数据状态，取值范围为：3（一次传完）

# 2、返回参数说明

参数名	类型	描述
header	object	协议头部
header.sid	string	本次会话id
header.code	int	返回码 0表示会话调用成功（并不一定表示服务调用成功，服务是否调用成功以text字段中的ret为准）其它表示会话调用异常
header.message	string	描述信息
payload	object	数据段，用于携带响应的数据
payload.output_result	object	文本纠错响应数据块
payload.output_result.compress	string	文本压缩格式，仅在设置了parameter.s9a87e3ec.result.compress参数时返回
payload.output_result.encoding	string	文本编码，仅在设置了parameter.s9a87e3ec.result.encoding参数时返回
payload.output_result.format	string	文本格式，仅在设置了parameter.s9a87e3ec.result.format参数时返回
payload.output_result.text	string	文本纠错返回结果，需要对其进行base64解码，解码后的返回字段如下

text字段base64解码后参数说明：

参数名	类型	描述
umeiTransactionId	string	日志id
code	int	返回code码,200成功，其他失败
msg	string	返回提示
data	object	纠错数据
data.checklist	array	纠错集合
data.checklist[n].wordHtml	string	可能含有html的错误词例如：蓝球
data.checklist[n].explanation	string	解释说明
data.checklist[n].word	string	错误词
data.checklist[n].context	string	错词上下文
data.checklist[n].position	int	错误词在文本中的开始位置
data.checklist[n].length	int	错误词的长度
data.checklist[n].source	int	无需关注，预留字段
data.checklist[n].type	object	类型说明
data.checklist[n].type.id	int	能力一级ID
data.checklist[n].type.belongId	int	能力归属ID
data.checklist[n].type.name	string	错误名称
data.checklist[n].type.desc	string	错误描述
data.checklist[n].action	object	纠错动作
data.checklist[n].action.id	int	纠错具体动作： 1 标记 2 替换 4 删除
data.checklist[n].htmlWords	array	错误词集合
data.checklist[n].htmlWords[n].word	string	错误词
data.checklist[n].htmlWords[n].position	int	错误词开始位置
data.checklist[n].suggest	array	建议集合
data.checklist[n].suggest[n]	string	具体建议详情

# 3、错误能力ID对照表

错误能力ID（belongId）	说明
9	错别字、词
31	多字错误
32	少字错误
35	语义重复
34	语序错误
39	量和单位差错
36	数字差错
20	句式杂糅
21	标点符号差错
24	句子查重
119	重要讲话引用
123	地理名词
19	机构名称
124	专有名词及术语
122	媒体报道禁用词和慎用词
6	常识差错
111	涉低俗辱骂
118	其他敏感内容

# 常见问题

# 公文校对与文本纠错、文本合规有哪些区别？

答：文本纠错主要偏向通用领域（如写作、出版）文本进行纠错，公文校对在公文写作使用等领域效果更佳，同时也适合通用领域。文本合规对各类场景风险拦截更全面。

# 公文校对position仅标记开始位置，结束位置怎么计算呢？

答：公文校对给出position的同时，也给出了length错误词长度，用position+length就是对应错误词在文本中的结束位置。

# 公文校对的文本有什么要求吗？

答：原请求的校对文本不能为空且不能超过220000个字符，汉字、英文字母、标点都算做一个字符

在这篇文章中：