本文记录文档转码使用过程中，遇到的常见问题。

接口使用问题

文档转码的作用是什么呢？为什么互动白板需要配合使用文档转码？

文档转码的作用，是把本地文档，转码成线上可查看的一种方式（如把 PPT 转码成 H5）。
互动白板 使用过程中，老师需要将自己的课件，展示给学生观看，这时就需要通过文档转码，将老师的课件转成线上可查看，然后学生就可以看到老师的课件了。

文档转码支持单独接入使用吗？

不支持。目前文档转码，只能配合 互动白板 使用。若您的互动白板服务未产生时长消耗，却调用了文档转码服务，则您发起的转码任务会被低优先级处理，可能出现长时间排队的情况。

为什么不建议使用 互动白板 SDK 的 addTranscodeFile 发起文档转码呢？

由于文档转码存在转码耗时和排队耗时，建议使用服务端 API 提前转码，客户端直接使用转码结果。不建议直接在客户端调用互动白板 SDK 的转码接口addTranscodeFile，避免长时间的等待，影响产品体验。

如果出现转码失败，是否需要业务侧重试呢？

不需要。因为转码服务器内部，已经加了转码失败的重试逻辑，业务侧无需重试（服务器重试逻辑：每台服务器重试3次，尝试2台转码服务器）。

服务端 API，Region 支持哪些区域呢？

目前服务端 API 接口只支持区域广州，在调用腾讯云 API 发起转码、查询转码结果时，Region参数请填写ap-guangzhou。

如何在 SDK 中使用转码结果？

请参考 互动白板 各个平台 API 文档中的 addTranscodeFile 接口说明。

文档转码后的文件，存储在哪里呢？

建议设置 存储桶配置，这样转码后的文件会自动转存到用户配置的 COS 桶里。如果没有设置 存储桶配置，则默认存储在腾讯云转码服务器默认的 COS 桶，存储周期为7天；7天后，转码文件自动删除。

文档转码是怎么收费的呢？

具体收费标准，请参考 购买指南。

事件回调问题

为什么有时会出现长时间接收不到事件回调呢？

1. 转码和录制，回调的超时时间为10s，如果回调失败，会间隔5s，最大重试5次。2. 如果长时间收不到回调，并且确认回调地址正常可用，可能原因如下：回调 URL 和服务器的 RTT 超过了10s。回调因为网络原因丢失了。3. 所以建议在代码逻辑中加上：如果出现长时间收不到回调时，配合查询任务进度接口确认。

缩略图问题

静态和动态转码都支持缩略图吗？怎么生成？

静态 和 动态转码都支持缩略图。只需要在 发起文档转码 CreateTranscode 时，传入参数 ThumbnailResolution 参数，并且指定分辨率即可。例如，传入 "ThumbnailResolution":"640x480"，转码结果里，即可看到 "ThumbnailUrl":"http://xxxx/xxx/" 缩略图 URL 地址

为什么调用互动白板 getThumbnailImages 获取缩略图地址接口，有时返回的缩略图地址无法打开呢？

1. 互动白板 getThumbnailImages 的内部实现，只是根据固定的规则，组装缩略图地址；无法验证缩略图地址是否真实有效；所以如果需要缩略图功能，转码时请务必传入 ThumbnailResolution 参数2. 静态转码 如果用户没有开通 存储桶配置，getThumbnailImages 会把文档转码结果 ResultUrl 按照固定规则修改成缩略图地址。但是 动态转码 ResultUrl 是 后 H5 链接，无法修成缩略图地址；所以现象就是，静态转码 缩略图正常，但是 动态转码 的缩略图地址打开 http 404 错误。所以如果需要缩略图功能，转码时请务必传入 ThumbnailResolution 参数。

转码耗时问题

文档转码，大概会耗时多久呢？

PPT 动态转码成 HTML5 大约为1s/页，静态转码成图片大约为0.5s/页。

为什么有时，转码耗时很长？

1. 文档转码资源有限，存在排队逻辑；当高峰时段，转码量过多时，新的任务会进入排队逻辑 被有序转码；所以就会增加排队时间。2. 建议老师提前备课，错开高峰期转码；以免上课时转码时间过长，影响上课体验。

为什么发起转码后，长时间收不到转码回调呢？

1. 确认已经设置了回调，并且回调地址可用；设置回调，可以参考 回调设置。2. 转码正在排队中。可以通过 查询转码任务 接口确认；如果返回的 Status 为 “QUEUED”；则代表正在排队中。

网络问题

为什么会提示，文档 URL 解析错误呢？URL 具体的要求是什么呢？

1. 目前只支持以 http:// 或 https:// 前缀的 URL。2. 请确保文档下载 URL 的 path 后缀，以 ppt(x)/doc(x)/pdf 结尾；否则下载 URL 会校验失败。

为什么会提示，文档下载失败呢？

1. 请确认文档 URL 的访问权限，并且可以通过浏览器正常下载；2. 如果是 云服务器 COS 桶，请确认访问权限是否为公有读私有写，或者签名是否过期。

为什么会提示，文档下载超时呢？

1. 转码服务器，默认下载超时时间为60s（防止因为下载时间过长，过多占用服务器资源），建议文档最好不要超过200M，防止文档过大，导致下载超时。2. 如果使用腾讯云 COS 桶存储，下载理论可以走腾讯云内网，所以可以支持更大的文件下载。

文档格式问题

文档转码，支持哪些格式呢？

动态演示文件：pptx、ppt；静态演示文件：pptx、ppt；文字文件：doc、docx；图片文件：jpg、jpeg、png、bmp；音频文件：MP3 ；视频文件：MP4 ；H5 文件：htm、 html；其他格式文件：pdf；推荐转码方案暂时不支持文件： excel 、xlsx、xltx、txt 格式，如需使用，可以使用备用转码方案。

ppt 动态转码，格式有哪些需要注意的地方呢？可以汇总一下吗？

1. 避免使用不支持转码的元素，如：”墨迹” ；可以通过 PowerPoint 打开 PPT，然后开始 > 选择 > 选择窗格 > 查看是否存在墨迹。2. 不支持5种动效；Bold Flash（加粗闪烁）、Underline（下划线）、Grow With Color（颜色渐变）、Bold Reveal（加粗显示）、Wipe（擦除）。3. 建议使用 Microsoft Office 2007或以上版本（WPS 和 keynote 都有一定的兼容性问题）。4. 转码文件必须是可编辑的。不支持“只读”、“加密”、或其他保护，导致 PPT 无法编辑的文件转码。5. 请勿插入 flash 动画，不支持 flash 动画播放。6. 如果使用 WPS，请注意不支持 WPS PPT 中的音视频元素。7. 如果使用 keynote，请注意插入的音频播放标签，无法展示。8. 建议使用操作系统默认的中英文字体，请勿使用自己安装的字体，否则可能会出现转码失败或者转码 H5 格式异常，点击查看 PPT 支持的字体列表。9. PPT 页数不要过多，页数越多，转换速度越慢（目前最大支持500页转码）。10. 尽量减小 PPT 体积大小，最好控制在50M以内；因为转码服务器，下载超时时间为1分钟；如果文件过大，可能会因为下载超时导致转码失败。11. 目前文档转码，对 PPT 中 内嵌音视频 支持不完善；不建议 PPT 中内嵌音视频，否则转码后的 H5 中，可能会遇到音视频播放失败或者本地和远端音视频不同步等问题。12. 建议不要在 PPT/PPTX 文档中，对文字添加荧光色背景。

转码如何保留动画呢？

1. 使用 PPT/PPTX 文档转码，默认会保留动画；2. 如果设置了 IsStaticPPT=true，则所有的文档都会转码成 静态图片(包括 PPT 文件)。

提交的文档，会转码成什么格式的文件呢？

1. 默认情况下，PPT/PPTX 文档会转码成 HTML5 页面，能够还原 PPT 原有的动画效果，其他文档转码成静态图片。2. 如果设置了 IsStaticPPT=true，则所有的文档都会转码成 静态图片(包括 PPT 文件)。

动态转码支持音视频吗？

目前对音视频支持不完善，不建议在 PPT/PPTX 中使用音视频

转码效果问题

动态转码出现某些字体错位，或大小不一致，如何处理？

1. 可能使用了转码服务器不支持的字体库导致，需要去除或修改不支持的字体 查看转码服务器支持字体。2. 对于动态转码和静态转码，如果遇到字体不支持的情况，也可以使用 Office 的将字体嵌入文件的功能。将字体嵌入文件，操作方法：Windows 端：打开文档，选择文件 > 选项 > 保存，然后勾选 将字体嵌入文件 > 嵌入所有字符(适于其他人编辑) > 确定 保存文档，看到 Office 的底部状态栏，显示正在嵌入字体即可如图所示：macOS 端：打开文档，选择 PowerPoint  > 偏好设置 > 保存，然后 勾选将字体嵌入文件 > 嵌入所有字符(适于其他人编辑) > 保存文档，看到 Office 的底部状态栏，显示正在嵌入字体即可。如图所示：


为什么有些 PPT 动效，转换为 H5 后，丢失了呢？

1. 确认没有使用转码不支持的4种动效 Bold Flash(加粗闪烁)、Underline(下划线)、Grow With Color(颜色渐变)、Bold Reveal(加粗显示)。2. 最好不要使用组合动效，因为组合动效过于复杂，加大了 H5 还原的难度。

转码错误码解析

错误码：-14 Occur issue in convert processing 是什么原因？该如何解决？

问题原因：PPT 的内容中含有不支持转码的元素
解决方法：需要根据错误信息中提示的具体页数，查看是否使用了 “墨迹” 和 4种不支持的动效。
查看墨迹方法：PowerPoint 打开 PPT > 依次选择开始 > 选择 > 选择窗格 > 查看右边框是否存在“墨迹”元素。如图所示：


错误码: -9 ppt to pptx failed! 是什么原因呢？该如何解决？

问题原因：PPT 转换成 PPTX 失败；可能是 PPT 使用的 PowerPoint 版本太老 或者 PPT 中含有某些元素，不支持转换成 PPTX 格式。
解决方法：PowerPoint 打开 PPT > 手动转换为 PPTX > 确认 PPTX 打开不会有任何报错 > 在使用转换后的 PPTX 重新发起转码。

错误码: -20 UnKnow Ppt property! 是什么原因呢？该如何解决？

问题原因：PPT/PPTX 文件，可能是“只读”、“加密”、或有其他保护，导致 PPT 无法被编辑。
解决方法：PowerPoint 打开 PPT/PPTX > 修复 PowerPoint 提示的错误 > 确保 PPT/PPTX 已经修改为可编辑 > 保存 > 重新发起文档转码。

错误码：-27 Download ppt data timeout! 是什么原因呢？该如何解决？

问题原因：PPT/PPTX 体积过大 或者 文档 URL 下载的带宽太小，导致转码服务器下载超时了；转码服务器目前下载超时时间为1分钟。
解决方法：1. 尝试去掉 PPT/PPTX 中占用体积较大的元素，例如音视频文件等。 2. 确认文档 URL 源站的下载带宽。

错误码：-106 download file suffix not support! 是什么原因呢？该如何解决？

问题原因：文档转码 的 URL path，不是以 ppt(x)/doc(x)/pdf 结尾（此处注意，URL 中 ?号后面的是参数，不是 path）。
解决方法：请确保文档下载 URL 的 path 后缀，以 ppt(x)/doc(x)/pdf 结尾；否则下载 URL 会校验失败。

其他问题

文档转码返回 URL 的有效期是多长时间？

1. 如果没有开通存储桶配置，转码后的文件存储在互动白板的 COS 桶里，默认存储时间是7天。7天后，存储桶里的转码文件自动删除，URL 的文件就会失效2. 强烈建议开通存储桶配置，这样转码后的文件，就可以自动转存到用户自己的 COS 桶下，不用担心转码文件过期的问题存储桶开通指南。

转码错误码对照表

文档转码 错误描述中的错误码列表



腾讯云官网1折活动，限时活动，即将结束，速速收藏
同尘科技为腾讯云授权服务中心。
购买腾讯云产品享受折上折，更有现金返利。同意关联立享优惠