度慧解文

度慧解文API（阿里）概述：

在线试用：

https://docudeep.com/

小程序：

使用方式：

第一步：用 文档添加GET 或 文档添加POST 添加文档，成功后获得token和owner，添加文档是异步操作，所以需要第二步查询添加结果

第二步：使用该token去轮询文档添加状态，见 查询文档添加结果 QUERY，直到添加完成。也可以设置callbackurl，当添加结束后，系统会回调该URL直接推送添加结果。详细见：回调URL

第三步：使用该token对文档提问，见 文档提问GET

API调用需要签名，详细见文档附录：阿里签名

阿里云支持从OSS内网直接下载文件，节约流量，见：阿里云独有部分

文档添加 / 替换GET

提供文档下载地址url来添加，type是源文档的type，比如要添加docx，type就是docx，默认type可以不填，会自动使用url的文件扩展名，但是如果url里的文件扩展名无法解析出来，则会报错。

请求参数:

请求示例:

https://gpt.market.alicloudapi.com/v1/add?url=https%3a%2f%2fxxx%2fxxx.docx&type=docx

添加所在url地址的docx文件，type就是源文件的type，这个例子里就是docx。

文档添加替换的接口都可以添加也可以替换文档。当添加文档时，如果指定了owner，那么返回的owner就是指定值，如果不指定，那么owner返回随机值。如要替换文档，必须指定需替换文档的token和owner。

请妥善保管owner作为替换，删除文档的唯一凭证，最好保留在服务器端避免泄漏。之后涉及到owner的地方都与此相同，不再赘述。

必须签名才能调用成功，签名见阿里签名规则:

https://help.aliyun.com/zh/api-gateway/traditional-api-gateway/use-cases/call-apis

支持多种文件格式，具体如下（type可传入如下格式）：

PDF文件：pdf

微软Office文档：doc, docx, ppt, pptx, xls, xlsx, pot, pps, ppsx

WPS文档：wps, wpt, dps, dpt, et, ett

苹果iWork文档：pages, key, numbers

开放版式文档：ofd

电子刊物：caj, nh, kdh

电子书：epub, chm, mobi, azw, azw3, fb2, cbr, cbz, djvu

Markdown格式：md

SVG格式: svg

网页文件：html, htm, mht, eml

图片文件：几乎所有格式例如png, jpg, jpeg, gif, tif, tiff, bmp, 可以统一传img，代表一切图片

文本文件：txt, rtf, java, js, c, cpp, jsp, css, xml, properties, log, 其他任意文本文件都可以传txt

网址网页：url（网址，例如：https://www.duhuitech.com）

返回数据结构:

result:

返回示例(成功状态):

{
  "code": 10000,
  "msg": "",
  "result": {
    "token": "xxx",
    "owner": "xxx"
  }
}

返回示例(失败状态):

{
  "code": 40001,
  "msg": "ParmNotRight"
}

文档添加 / 替换POST

直接将单个文档POST到服务器，大小限制8M

请求参数:

请求示例:

https://gpt.market.alicloudapi.com/v1/add

Header中的Content-Type必须是multipart/form-data

必须签名才能调用成功，签名见阿里签名规则:

https://help.aliyun.com/zh/api-gateway/traditional-api-gateway/use-cases/call-apis

支持多种文件格式，具体如下（type可传入如下格式）：

PDF文件：pdf

微软Office文档：doc, docx, ppt, pptx, xls, xlsx, pot, pps, ppsx

WPS文档：wps, wpt, dps, dpt, et, ett

苹果iWork文档：pages, key, numbers

开放版式文档：ofd

电子刊物：caj, nh, kdh

电子书：epub, chm, mobi, azw, azw3, fb2, cbr, cbz, djvu

Markdown格式：md

SVG格式: svg

网页文件：html, htm, mht, eml

图片文件：几乎所有格式例如png, jpg, jpeg, gif, tif, tiff, bmp, 可以统一传img，代表一切图片

文本文件：txt, rtf, java, js, c, cpp, jsp, css, xml, properties, log, 其他任意文本文件都可以传txt

返回数据结构:

result:

返回示例(成功状态):

{
  "code": 10000,
  "msg": "",
  "result": {
    "token": "xxx",
    "owner": "xxx"
  }
}

返回示例(失败状态):

{
  "code": 40001,
  "msg": "ParmNotRight"
}

多张图片添加 / 替换POST

添加多张图片，传入每张图片的地址，传入非图片格式无效，最多50张图片，或1张长图

Header中的Content-Type传入application/json

POST Body传入JSON，格式如下：

请求参数BODY:

请求示例:

https://gpt.market.alicloudapi.com/v1/add_images

传入的Body为JSON格式，如下：

{
  "url": [
    "http://xxx/xxx1.png",
    "http://xxx/xxx2.png"
  ]
}

必须签名才能调用成功，签名见阿里签名规则:

https://help.aliyun.com/zh/api-gateway/traditional-api-gateway/use-cases/call-apis

支持几乎所有图片格式

返回数据结构:

result:

返回示例(成功状态):

{
  "code": 10000,
  "msg": "",
  "result": {
    "token": "xxx",
    "owner": "xxx"
  }
}

返回示例(失败状态):

{
  "code": 40001,
  "msg": "ParmNotRight"
}

查询文档添加结果 QUERY

请求参数:

请求示例:

https://api.duhuitech.com/q?token=xxx

无需签名，无调用次数限制

由于添加需要时间，文件越大页数越多，添加越久，故需要轮询查询接口来获得结果。查询频率可以是1s一次，也可以更长一些。查询后先看status，如果是Done或Failed，则添加结束，停止轮询。如果是Doing或Pending，则继续轮询。

返回数据结构:

result:

返回示例(成功状态):

{
  "code": 10000,
  "msg": "",
  "token": "xxx",
  "result": {
    "progress": 0.02,
    "status": "Doing"
  }
}

{
  "code": 10000,
  "msg": "",
  "token": "xxx",
  "result": {
    "status": "Done",
    "count": 10
  }
}

返回示例(失败状态):

{
  "code": 40400,
  "msg": "No such token",
  "token": "xxx"
}

文档提问GET / POST

对文档进行提问，总结，信息提取，翻译等。其中提问通过parentid参数支持上下文。

请求参数:

请求示例:

GET：

https://gpt.market.alicloudapi.com/v1/ask?token=xxx&action=question&parm=%E6%94%AF%E6%8C%81%E5%8E%8B%E7%BC%A9%E5%90%97%EF%BC%9F

POST:
https://gpt.market.alicloudapi.com/v1/ask

由于参数在body里，所以可以不需要做urlencoding

如果参数较长，建议POST方式，GET方式参数长度有限制

必须签名才能调用成功，签名见阿里签名规则:

https://help.aliyun.com/zh/api-gateway/traditional-api-gateway/use-cases/call-apis

返回数据结构:(stream为0时)

result:

返回示例(成功状态):

{
  "code": 10000,
  "msg": "",
  "token": "xxx",
  "result": {
    "answer": "xxx",
    "parentid": "xxx"
  }
}

返回示例(失败状态):

{
  "code": 40001,
  "msg": "ParmNotRight"
}

返回数据结构:(stream为1时)

返回content-type: text/event-stream

Type: message

Data: 'xxx'

注意data里的数据前后被 ' 包围，使用时要去掉 '

如果action是提问question，最后一行会返回parentid：

Type: parentid

Data: xxx

注意data里没有 ' 包围

异步返回模式:

当开启了async=1，那么api会立即返回queryid，同时不会进行stream流式输出：

{
  "code": 10000,
  "msg": "",
  "token": "xxx",
  "result": {
    "queryid": "xxx",
    "status": "Doing"
  }
}

然后通过轮询 查询提问结果QUERY 接口，来获得结果。

异步查询提问结果 QUERY

请求参数:

请求示例:

https://gpt.market.alicloudapi.com/v1/result?token=xxx&queryid=xxx

必须签名才能调用成功，签名见阿里签名规则:

https://help.aliyun.com/zh/api-gateway/traditional-api-gateway/use-cases/call-apis

查询频率建议3-5秒。查询后先看status，如果是Done或Failed，则结束，停止轮询。如果是Doing，则继续轮询。

返回数据结构:

result:

返回示例(成功状态):

{
"code":10000,
"msg":"",
"token":"xxx",
"result":
{
"queryid":xxx,
"status":"Doing"
}
}

{
  "code": 10000,
  "msg": "",
  "token": "xxx",
  "result": {
    "status": "Done",
    "queryid": "xxx",
    "content": "xxx",
    "parentid": "xxx"
  }
}

返回示例(失败状态):

{
  "code": 40500,
  "msg": "NoSuchQueryId",
  "token": "xxx"
}

文档分享GET

分享文档的URL，获得该URL的用户都可以提问。

请求参数:

请求示例:

https://gpt.market.alicloudapi.com/v1/share?token=xxx&owner=xxx&appcode=xxx&filename=xxx

必须签名才能调用成功，签名见阿里签名规则:

https://help.aliyun.com/zh/api-gateway/traditional-api-gateway/use-cases/call-apis

返回数据结构:

result:

返回示例(成功状态):

{
  "code": 10000,
  "msg": "",
  "token": "xxx",
  "result": {
    "shareurl": "xxx"
  }
}

返回示例(失败状态):

{
  "code": 40001,
  "msg": "ParmNotRight"
}

文档删除GET

删除文档，对不需要再次提问的文档，可以删除。

请求参数:

请求示例:

https://gpt.market.alicloudapi.com/v1/delete?token=xxx&owner=xxx

必须签名才能调用成功，签名见阿里签名规则:

https://help.aliyun.com/zh/api-gateway/traditional-api-gateway/use-cases/call-apis

返回数据结构:

返回示例(成功状态):

{
  "code": 10000,
  "msg": "",
  "token": "xxx"
}

返回示例(失败状态):

{
  "code": 40001,
  "msg": "ParmNotRight"
}

注意：

• 上传文件单个最大1500M

• 多张图片一次最多50张

• 支持单张长图

• 文件有条件永久保留，如果文件1个月内没有提问，则会被自动删除

回调URL：

用途：客户可以自行部署服务器，文件添加结束后会调用客户提供的回调URL，直接发送添加结果，从而无需再轮询Query。

当设置了回调URL，添加结束后（无论成功失败），系统都会尝试调用该URL，具体如下：

以POST方式调用该URL，Header头中Content-Type: application/json

Body为JSON格式，内容和Query的结果相同，例如：

{
  "code": 10000,
  "msg": "",
  "token": "xxx",
  "result": {
    "status": "Done",
    "count": 10
  }
}

服务端收到该POST后需在10秒内返回HTTP STATUS CODE 200，视为调用成功，否则系统认为回调失败，会再次尝试。规则如下：

系统共计最多会调用3次回调URL，如果第一次失败，则等待3秒后尝试第二次，如果第二次失败，则等待5秒后尝试第三次，如果第三次失败，则不再尝试。

回调URL超时时间10秒。

阿里云独有部分：

支持从阿里云OSS内网直接下载文件，目前支持的是上海地区的阿里云OSS内网：

oss-cn-shanghai-internal.aliyuncs.com

文档转换GET里的url地址包含上述域名则自动支持

错误码表：

附录：自定义输出JSON格式

支持的数据类型：

String

Number

Boolean

Integer

Object

Array

Enum

anyOf

以下是每个类型及用法

String

说明：表示字符串类型。

写法：填写 "str" 或 "String"。

示例：

{
  "companyName": "str"
}

Number

说明：表示数字类型（浮点数）。

写法：填写 "Number" 或 "float"。

示例：

{
  "revenue": "Number"
}

Boolean

说明：表示布尔值（True/False）。

写法：填写 "Boolean" 或 "bool"。

示例：

{
  "active": "Boolean"
}

Integer

说明：表示整数类型。

写法：填写 "Integer" 或 "int"。

示例：

{
  "founded": "Integer"
}

Object

说明：用于描述嵌套对象，即由若干字段构成的子模型。

写法：直接使用一个字典，键为子字段名称，值为其类型定义。

示例：

{
  "headquarters": {
    "address": "str",
    "openHours": {
      "weekdays": "list[str]",
      "weekend": "list[str]"
    }
  }
}

Array

说明：用于描述数组类型，所有元素必须为同一种类型。

写法：有两种方式：

使用列表形式，列表内只包含一个类型定义，如 ["str"]，表示每项是字符串。

示例：

{
  "tags": [
    "str"
  ]
}

或者使用简写字符串形式，直接写成 "list[子类型]"，例如 "list[str]"。

示例：

{
  "skills": "list[str]"
}

Enum

说明：用于限定取值范围，只允许取预定义的几个值。

写法：使用 "Enum[值1, 值2, 值3]" 格式。

示例：

{
  "status": "Enum[planned, active, completed]"
}

anyOf

说明：表示联合类型，字段的值可以是多种类型中的任意一种。

写法：使用 "anyOf[类型1, 类型2, ...]" 格式。

示例：

{
  "score": "anyOf[int, Number]"
}

完整示例

下面是一个完整例子，该定义描述了一个公司信息模型，含多层嵌套的对象和数组：

{
"companyName": "str",
"founded": "Integer",
"departments": [ # 部门数组（第一层数组中的每个元素为对象）
{
"deptName": "str",
"budget": "Number",
"employees": [ # 员工数组
{
"empName": "str",
"age": "Integer",
"skills": "list[str]", # 技能数组
"certifications": { # 认证信息对象，包含数组
"certList": "list[str]",
"valid": "Boolean"
}
}
],
"projects": [ # 部门项目数组
{
"projectName": "str",
"startDate": "str",
"status": "Enum[planned, active, completed]",
"milestones": [ # 里程碑数组（第三层嵌套）
{
"milestoneName": "str",
"dueDate": "str"
}
]
}
]
}
],
"headquarters": { # 总部信息对象
"address": "str",
"coordinates": "list[Number]", # 坐标数组
"openHours": {
"weekdays": "list[str]",
"weekend": "list[str]"
}
}
}

公司基本信息（公司名称、成立年份）。

部门数组（第一层数组），每个部门包含部门名称、预算、员工信息和部门项目。

部门中的 员工数组：每个员工具有姓名、年龄、技能数组和认证信息（一个对象，其中包含认证列表数组和是否有效标识）。

部门中的 项目数组：每个项目包含项目名称、开始日期、状态（枚举）以及 里程碑数组（第三层嵌套，每个里程碑具有名称和截止日期）。

总部信息对象，包含地址、坐标数组和营业时间（分别针对工作日和周末）。

使用说明

• 用户需要输入一个 JSON 定义，形式必须为字典（键值对），各字段的值使用上面提到的类型标识。

• 数组类型可以写成列表形式（如 ["str"]）或用 "list[...]" 的字符串形式；注意整个 JSON 定义仍必须是字典。

• 对于枚举类型，请使用 "Enum[...]"，不同选项之间用逗号分隔。

• 如果需要联合多种类型，请使用 "anyOf[...]" 格式。

• 嵌套对象只需直接写子字段及其类型，无需额外的 "type"、"properties" 等标识。

附录：阿里签名方式仅适用于阿里云市场

参考链接：

https://help.aliyun.com/zh/api-gateway/traditional-api-gateway/use-cases/call-apis

在调用API商品时，首先您需要了解采用哪种API认证方式，云市场API商品的认证方式主要有以下两种方式。两种方式可同时使用，您可以根据不同情况来选择。

• 简单身份认证（AppCode）

• 签名认证

简单身份认证（AppCode）

简单认证（AppCode）调用API，有两种方式，一种是将AppCode放在Header中进行调用，一种是将AppCode放在Query参数中进行调用。

方式一：将AppCode放在Header中

在请求Header中添加一个Authorization参数。

Authorization字段的值的格式为APPCODE ＋ 半角空格 ＋APPCODE值。格式如下：

Authorization:APPCODE AppCode值

示例：

Authorization:APPCODE YOUR_ALIYUN_APPCODE

方式二：将AppCode放在Query中

在请求Query中添加AppCode参数（同时支持appcode , appCode , APPCODE , APPCode四种写法）。

AppCode参数的值为AppCode的值。

示例：

https://YOUR_ALIYUN_API_HOST/PATH?AppCode=YOUR_ALIYUN_APPCODE

参考链接：https://help.aliyun.com/zh/api-gateway/traditional-api-gateway/user-guide/call-an-api-operation-by-using-an-appcode

签名认证

比较复杂，推荐用阿里自己的SDK来调用，参考链接：https://help.aliyun.com/zh/api-gateway/traditional-api-gateway/user-guide/use-digest-authentication-to-call-an-api