外观
文件转 Markdown API 文档
说明
Hi，您好，欢迎使用有道智云文件转 Markdown API接口服务。
本文档主要针对需要集成HTTP API的技术开发工程师，详细描述文件转 Markdown能力相关的技术内容。
如果您有与我们商务合作的需求，可以通过以下方式联系我们：
商务邮箱： AIcloud_Business@corp.youdao.com
如果您对文档内容有任何疑问，可以通过以下几种方式联系我们：
客服QQ：1906538062
智云翻译技术交流QQ 1群: 652880659
智云翻译技术交流QQ 2群: 669384425
智云翻译技术交流QQ 3群: 807539209
智云翻译技术交流QQ 4群: 936752411
联系邮箱： zhiyun@corp.youdao.com
温馨提示：
- 本文档主要针对开发人员，接入测试前需要获取应用ID和应用密钥；如果您还没有，请按照 新手指南 获取。
- 平台向每个账户赠送50元的体验金，供用户集成前测试所用.
接口说明
文件转 Markdown API接口提供有道的PDF等各种文件转 Markdown服务。您只需要通过调用 API，传入文档的二进制数据，通过POST请求方式，就可以将文档中的文字内容进行转换。
协议须知
调用方在集成pdf转markdown API时，请遵循以下规则。
| 规则 | 描述 |
|---|---|
| 传输方式 | HTTPS |
| 请求方式 | POST |
| 字符编码 | 统一使用UTF-8 编码 |
| 请求格式 | 表单 |
| 响应格式 | JSON |
文件转 Markdown API HTTPS地址：
1. 提交转换任务
接口路径： POST https://openapi.youdao.com/proxy/http/file2md-upload
Content-Type： multipart/form-data
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| appKey | String | 是 | 智云平台应用 Key |
| salt | String | 是 | 签名随机生成的随机数 |
| sign | String | 是 | 签名（SHA-256，详见签名规则） |
| curtime | String | 是 | 当前时间戳（秒） |
| file | File | 是 | 待转换的文件（支持pdf, doc, docx, ppt, pptx 格式）, 文件名需要规范 .pdf / .doc / .docx / .ppt / .pptx格式 |
签名规则（v4）
sign = SHA256(appKey + salt + curtime + appSecret)返回示例
成功（HTTP 200）
json
{
"code": "0",
"message": "成功",
"data": {
"taskId": "a1b2c3d4e5f6..."
},
"requestId": "xxx"
}失败
json
{
"code": "907001",
"message": "文件转换服务调用失败，请稍后重试",
"data": null,
"requestId": "xxx"
}错误码
| code | 说明 |
|---|---|
| 101 | 缺少必填的参数，首先确保必填参数齐全，然后，确认参数书写是否正确。 |
| 102 | 不支持的语言类型 |
| 103 | 翻译文本过长 |
| 104 | 不支持的API类型 |
| 105 | 不支持的签名类型 |
| 106 | 不支持的响应类型 |
| 107 | 不支持的传输加密类型 |
| 108 | 应用ID无效，注册账号，登录后台创建应用和实例并完成绑定，可获得应用ID和应用密钥等信息 |
| 109 | batchLog格式不正确 |
| 110 | 无相关服务的有效实例，应用没有绑定服务实例，可以新建服务实例，绑定服务实例。注：某些服务的结果发音需要tts实例，需要在控制台创建语音合成实例绑定应用后方能使用。 |
| 111 | 开发者账号无效 |
| 112 | 请求服务无效 |
| 113 | q不能为空 |
| 114 | 不支持的图片传输方式 |
| 201 | 解密失败，可能为DES,BASE64,URLDecode的错误 |
| 202 | 签名检验失败，如果确认应用ID和应用密钥的正确性，仍返回202，一般是编码问题。请确保 img 为 UTF-8 编码. |
| 203 | 访问IP地址不在可访问IP列表 |
| 205 | 请求的接口与应用的平台类型不一致，确保接入方式（Android SDK、IOS SDK、API）与创建的应用平台类型一致。如有疑问请参考入门指南 |
| 206 | 因为时间戳无效导致签名校验失败 |
| 207 | 重放请求 |
| 0 | 成功 |
| 907001 | 文件转换服务调用失败 |
| 907004 | 文件页数获取失败 |
| 907005 | 存储异常，请联系管理员 |
2. 查询转换结果
接口路径： POST https://openapi.youdao.com/proxy/http/file2md-query
Content-Type： application/x-www-form-urlencoded
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| appKey | String | 是 | 智云平台应用 Key |
| salt | String | 是 | 签名随机盐 |
| sign | String | 是 | 签名（SHA-256，详见签名规则） |
| curtime | String | 是 | 当前时间戳（秒） |
| taskId | String | 是 | 任务 ID（由上传接口返回） |
签名规则（v4）
sign = SHA256(appKey + salt + curtime + appSecret)返回示例
处理中
json
{
"code": "0",
"message": "成功",
"data": {
"status": "PROCESSING"
},
"requestId": "xxx"
}转换成功
json
{
"code": "0",
"message": "成功",
"data": {
"status": "SUCCESS",
"mdResult": "# 标题\n\n正文内容..."
},
"requestId": "xxx"
}转换失败
json
{
"code": "0",
"message": "成功",
"data": {
"status": "FAILED"
},
"requestId": "xxx"
}错误码
| code | 说明 |
|---|---|
| 0 | 成功（status 字段表示转换状态） |
| 101 | 缺少必填的参数，首先确保必填参数齐全，然后，确认参数书写是否正确。 |
| 102 | 不支持的语言类型 |
| 103 | 翻译文本过长 |
| 104 | 不支持的API类型 |
| 105 | 不支持的签名类型 |
| 106 | 不支持的响应类型 |
| 107 | 不支持的传输加密类型 |
| 108 | 应用ID无效，注册账号，登录后台创建应用和实例并完成绑定，可获得应用ID和应用密钥等信息 |
| 109 | batchLog格式不正确 |
| 110 | 无相关服务的有效实例，应用没有绑定服务实例，可以新建服务实例，绑定服务实例。注：某些服务的结果发音需要tts实例，需要在控制台创建语音合成实例绑定应用后方能使用。 |
| 111 | 开发者账号无效 |
| 112 | 请求服务无效 |
| 113 | q不能为空 |
| 114 | 不支持的图片传输方式 |
| 201 | 解密失败，可能为DES,BASE64,URLDecode的错误 |
| 202 | 签名检验失败，如果确认应用ID和应用密钥的正确性，仍返回202，一般是编码问题。请确保 img 为 UTF-8 编码. |
| 203 | 访问IP地址不在可访问IP列表 |
| 205 | 请求的接口与应用的平台类型不一致，确保接入方式（Android SDK、IOS SDK、API）与创建的应用平台类型一致。如有疑问请参考入门指南 |
| 206 | 因为时间戳无效导致签名校验失败 |
| 207 | 重放请求 |
| 907002 | 任务不存在（taskId 错误） |
| 907003 | 无权查询该任务（appKey 不匹配） |
3. 调用流程
1. 调用 /http/file2md-upload 上传文件，获取 taskId
2. 轮询 /http/file2md-query 查询结果
- status=PROCESSING：继续等待，建议间隔 3~10 秒
- status=SUCCESS：mdResult 即为 Markdown 内容
- status=FAILED：转换失败，可重新提交