---
name: document-conversion-file-processing
description: "当用户需要使用咕咕数据公开 API 完成文档自动化、业务数据组合、参数传递、接口选型或结果校验时使用；不适用于绕过接口详情页、购买规则或人工复核要求的场景。"
---

# 文档转换与文件处理 Skill

面向 PDF、Word、HTML、Markdown、PPT 与图片转换、拆分、识别和内容归档的公开 API 组合。

## 业务场景

用于文档自动化、内容归档、合同处理、报告生成和格式转换。适合把 PDF、Word、HTML、Markdown、PPT、图片和 OCR 相关接口组合成文档采集、转换、拆分和整理链路。

- 数据范围：覆盖 URL/HTML/Markdown/PDF/Word/PPT/图片相关转换、PDF 拆分、文档摘要、OCR、图片压缩和文档内容整理。
- 关键数据维度：文件维度：文件类型、页数、大小、来源 URL、转换目标和输出格式。；内容维度：正文、标题、段落、表格、图片、OCR 结果和摘要。；处理维度：转换、拆分、压缩、识别、提取和归档。

## 何时使用

- 把网页、PDF、Word、Markdown、HTML 或图片转换为业务需要的格式。
- 拆分、压缩、识别或整理文档，方便归档和后续处理。
- 为报告生成、资料入库、合同流转和内容发布准备文档数据。

## 不适用场景

- 用户只需要查看某一个接口的完整参数、响应字段、价格或购买入口时，直接打开接口详情页。
- 用户希望绕过接口开通、鉴权、配额或人工复核要求时，不应使用 Skill 作为替代。
- 任务需要法律、医疗、金融投资或升学录取的最终决策时，Skill 只能提供数据辅助和复核线索。

## 用户需要提供的信息

- 原始文件、URL 或 HTML 内容，以及目标格式、页码范围、文件大小和输出用途。
- 是否需要 OCR、摘要、拆分、压缩、转换或归档。
- 调用接口所需的 AppKey、开通状态和接口详情页限制。

## 推荐工作流

1. 先按输入格式选择解析或转换接口。
2. 再根据结果输出 PDF、Word、HTML、图片或纯文本。
3. 需要分段处理时，先拆分 PDF 或转换成中间格式。

## 参数传递关系

- 文件 URL、上传结果或 HTML 内容先进入转换接口，转换后的文本或文件地址再进入摘要、OCR、拆分或归档步骤。
- 拆分和转换任务需要保留页码范围、目标格式和原文件名。
- OCR 结果可继续传给文本处理 Skill 做摘要、纠错或结构化。

## 典型任务模板

- 格式转换：输入文件或 URL、目标格式；输出转换结果、失败原因和文件链接。
- 文档拆分：输入 PDF、页码范围；输出拆分文件和页码映射。
- 扫描件整理：输入图片或 PDF；输出 OCR 文本、摘要和人工复核项。

## 接口与关键参数

统一鉴权：调用接口前需要准备咕咕数据 AppKey。推荐在服务端通过 Header 传递 AppKey；历史 Query 参数 `appkey` 仍以接口详情页说明为准。

### HTML/URL 转 PDF

- 业务角色：HTML 转 PDF
- 调用阶段：转换输出
- 接口地址：`POST https://api.gugudata.com/imagerecognition/html2pdf`
- 产出用途：用于把 HTML 或 URL 转成 PDF。
- 参数来源：文本内容来自用户输入、网页正文抽取或文档识别结果；文件或图片来自用户上传、公开 URL 或上一轮转换结果
- 接口详情页：https://www.gugudata.com/api/details/html2pdf
- 接口 Markdown：https://www.gugudata.com/api/details/html2pdf/llm.md

关键请求参数：

| 参数 | 必填 | 类型 | 默认值 | 说明 | 来源与传递 |
| --- | --- | --- | --- | --- | --- |
| `type` | 是 | `string` | YOUR_VALUE | 可选参数为 HTML 或 URL（注意，当类型为 URL 时，需要保证页面可以正常请求，我们的接口不解决加密页面、反爬虫页面等不能正常返回 HTML 的页面请求） | 由用户输入、业务筛选条件或上一轮接口结果确定。 |
| `content` | 是 | `string` | YOUR_VALUE | 内容正文，如果 type=HTML，那么传递 HTML 内容；如果 type=URL，那么传递需要存储为 PDF 的站点 URL 即可 | 文本内容来自用户输入、网页正文抽取或文档识别结果 |
| `landscape` | 否 | `integer` | 0 | 控制生成 PDF 是否为横向页面模式，传递 1 控制页面横向渲染模式，默认为 0 | 由用户输入、业务筛选条件或上一轮接口结果确定。 |
| `showpages` | 否 | `integer` | 0 | 控制生成的 PDF 是否在页脚包含页码信息，传递 1 控制页脚生成页码，默认为 0 | 由用户输入、业务筛选条件或上一轮接口结果确定。 |
| `filename` | 否 | `string` | N/A | 可选参数，控制生成的文件名称，不需要后缀 | 文件或图片来自用户上传、公开 URL 或上一轮转换结果 |
| `storage` | 否 | `string` | public | 文件存储方式，可选 public 或 private。默认 public 返回公开下载地址；private 存入私有存储，返回 file_id，需生成短期下载链接后下载。 | 由用户输入、业务筛选条件或上一轮接口结果确定。 |

### HTML 转 Word

- 业务角色：HTML 转 Word
- 调用阶段：转换输出
- 接口地址：`POST https://api.gugudata.com/imagerecognition/html2word`
- 产出用途：用于把 HTML 转成 Word。
- 参数来源：文本内容来自用户输入、网页正文抽取或文档识别结果；文件或图片来自用户上传、公开 URL 或上一轮转换结果
- 接口详情页：https://www.gugudata.com/api/details/html2word
- 接口 Markdown：https://www.gugudata.com/api/details/html2word/llm.md

关键请求参数：

| 参数 | 必填 | 类型 | 默认值 | 说明 | 来源与传递 |
| --- | --- | --- | --- | --- | --- |
| `type` | 是 | `string` | YOUR_APPKEY | 可选参数为 HTML 或 URL（注意，当类型为 URL 时，需要保证页面可以正常请求，我们的接口不解决加密页面、反爬虫页面等不能正常返回 HTML 的页面请求） | 由用户输入、业务筛选条件或上一轮接口结果确定。 |
| `content` | 是 | `string` | YOUR_VALUE | 内容正文，如果 type=HTML，那么传递 HTML 内容；如果 type=URL，那么传递需要存储为 Word 的站点 URL 即可 | 文本内容来自用户输入、网页正文抽取或文档识别结果 |
| `filename` | 否 | `string` | N/A | 可选参数，控制生成的文件名称，不需要后缀 | 文件或图片来自用户上传、公开 URL 或上一轮转换结果 |
| `storage` | 否 | `string` | public | 文件存储方式，可选 public 或 private。默认 public 返回公开下载地址；private 存入私有存储，返回 file_id，需生成短期下载链接后下载。 | 由用户输入、业务筛选条件或上一轮接口结果确定。 |

### Markdown 转 PDF

- 业务角色：Markdown 转 PDF
- 调用阶段：转换输出
- 接口地址：`POST https://api.gugudata.com/imagerecognition/markdown2pdf`
- 产出用途：用于把 Markdown 转成 PDF。
- 参数来源：文本内容来自用户输入、网页正文抽取或文档识别结果
- 接口详情页：https://www.gugudata.com/api/details/markdown2pdf
- 接口 Markdown：https://www.gugudata.com/api/details/markdown2pdf/llm.md

关键请求参数：

| 参数 | 必填 | 类型 | 默认值 | 说明 | 来源与传递 |
| --- | --- | --- | --- | --- | --- |
| `content` | 是 | `string` | YOUR_VALUE | Markdown 内容 | 文本内容来自用户输入、网页正文抽取或文档识别结果 |
| `storage` | 否 | `string` | public | 文件存储方式，可选 public 或 private。默认 public 返回公开下载地址；private 存入私有存储，返回 file_id，需生成短期下载链接后下载。 | 由用户输入、业务筛选条件或上一轮接口结果确定。 |

### Word 转 HTML

- 业务角色：Word 转 HTML
- 调用阶段：转换输入
- 接口地址：`POST https://api.gugudata.com/imagerecognition/word-to-html`
- 产出用途：用于把 Word 转成 HTML。
- 参数来源：文件或图片来自用户上传、公开 URL 或上一轮转换结果
- 接口详情页：https://www.gugudata.com/api/details/word-to-html
- 接口 Markdown：https://www.gugudata.com/api/details/word-to-html/llm.md

关键请求参数：

| 参数 | 必填 | 类型 | 默认值 | 说明 | 来源与传递 |
| --- | --- | --- | --- | --- | --- |
| `file` | 是 | `string/binary` | - | Word 文档文件，支持 .doc 和 .docx 格式 | 文件或图片来自用户上传、公开 URL 或上一轮转换结果 |
| `storage` | 否 | `string` | public | 文件存储方式，可选 public 或 private。默认 public 返回公开下载地址；private 存入私有存储，返回 file_id，需生成短期下载链接后下载。 | 由用户输入、业务筛选条件或上一轮接口结果确定。 |

### PDF 解析格式化输出

- 业务角色：PDF 格式化
- 调用阶段：解析输入
- 接口地址：`POST https://api.gugudata.com/imagerecognition/pdf2format`
- 产出用途：用于 PDF 解析格式化输出。
- 参数来源：文件或图片来自用户上传、公开 URL 或上一轮转换结果
- 接口详情页：https://www.gugudata.com/api/details/pdf2format
- 接口 Markdown：https://www.gugudata.com/api/details/pdf2format/llm.md

关键请求参数：

| 参数 | 必填 | 类型 | 默认值 | 说明 | 来源与传递 |
| --- | --- | --- | --- | --- | --- |
| `type` | 是 | `string` | YOUR_VALUE | 定义输出格式，可选 text\|html\|xml\|tag | 由用户输入、业务筛选条件或上一轮接口结果确定。 |
| `pdffile` | 是 | `string/binary` | YOUR_VALUE | 文件格式参数，待转换的 PDF 文件 | 文件或图片来自用户上传、公开 URL 或上一轮转换结果 |

### PDF 转 HTML

- 业务角色：PDF 转 HTML
- 调用阶段：转换输入
- 接口地址：`POST https://api.gugudata.com/imagerecognition/pdf2html`
- 产出用途：用于把 PDF 转成 HTML。
- 参数来源：文件或图片来自用户上传、公开 URL 或上一轮转换结果
- 接口详情页：https://www.gugudata.com/api/details/pdf2html
- 接口 Markdown：https://www.gugudata.com/api/details/pdf2html/llm.md

关键请求参数：

| 参数 | 必填 | 类型 | 默认值 | 说明 | 来源与传递 |
| --- | --- | --- | --- | --- | --- |
| `file` | 是 | `string/binary` | YOUR_VALUE | formdata 文件流 | 文件或图片来自用户上传、公开 URL 或上一轮转换结果 |
| `storage` | 否 | `string` | public | 文件存储方式，可选 public 或 private。默认 public 返回公开下载地址；private 存入私有存储，返回 file_id，需生成短期下载链接后下载。 | 由用户输入、业务筛选条件或上一轮接口结果确定。 |

### 通用 PDF 文件流 OCR 到文本

- 业务角色：PDF 转文本
- 调用阶段：解析输入
- 接口地址：`POST https://api.gugudata.com/imagerecognition/pdf2text`
- 产出用途：用于 PDF 文件流 OCR 到文本。
- 参数来源：文件或图片来自用户上传、公开 URL 或上一轮转换结果
- 接口详情页：https://www.gugudata.com/api/details/pdf2text
- 接口 Markdown：https://www.gugudata.com/api/details/pdf2text/llm.md

关键请求参数：

| 参数 | 必填 | 类型 | 默认值 | 说明 | 来源与传递 |
| --- | --- | --- | --- | --- | --- |
| `pdffile` | 是 | `string/binary` | YOUR_VALUE | formdata 文件流 | 文件或图片来自用户上传、公开 URL 或上一轮转换结果 |

### 通用 PDF 文件流 OCR 到 Word

- 业务角色：PDF 转 Word
- 调用阶段：转换输出
- 接口地址：`POST https://api.gugudata.com/imagerecognition/pdf2word`
- 产出用途：用于 PDF 文件流 OCR 到 Word。
- 参数来源：文件或图片来自用户上传、公开 URL 或上一轮转换结果
- 接口详情页：https://www.gugudata.com/api/details/pdf2word
- 接口 Markdown：https://www.gugudata.com/api/details/pdf2word/llm.md

关键请求参数：

| 参数 | 必填 | 类型 | 默认值 | 说明 | 来源与传递 |
| --- | --- | --- | --- | --- | --- |
| `pdffile` | 是 | `string/binary` | N/A | formdata 文件流 | 文件或图片来自用户上传、公开 URL 或上一轮转换结果 |
| `storage` | 否 | `string` | public | 文件存储方式，可选 public 或 private。默认 public 返回公开下载地址；private 存入私有存储，返回 file_id，需生成短期下载链接后下载。 | 由用户输入、业务筛选条件或上一轮接口结果确定。 |

### PDF 分割拆分

- 业务角色：PDF 拆分
- 调用阶段：文档处理
- 接口地址：`POST https://api.gugudata.com/imagerecognition/pdf-splitter`
- 产出用途：用于 PDF 分割拆分。
- 参数来源：文件或图片来自用户上传、公开 URL 或上一轮转换结果
- 接口详情页：https://www.gugudata.com/api/details/pdfsplitter
- 接口 Markdown：https://www.gugudata.com/api/details/pdfsplitter/llm.md

关键请求参数：

| 参数 | 必填 | 类型 | 默认值 | 说明 | 来源与传递 |
| --- | --- | --- | --- | --- | --- |
| `file` | 是 | `string/binary` | YOUR_VALUE | formdata 文件流 | 文件或图片来自用户上传、公开 URL 或上一轮转换结果 |
| `storage` | 否 | `string` | public | 文件存储方式，可选 public 或 private。默认 public 返回公开下载地址；private 存入私有存储，返回 file_id，需生成短期下载链接后下载。 | 由用户输入、业务筛选条件或上一轮接口结果确定。 |

### PPT 转高精度 PDF

- 业务角色：PPT 转 PDF
- 调用阶段：转换输出
- 接口地址：`POST https://api.gugudata.com/imagerecognition/ppt-to-pdf`
- 产出用途：用于 PPT 转高精度 PDF。
- 参数来源：文件或图片来自用户上传、公开 URL 或上一轮转换结果
- 接口详情页：https://www.gugudata.com/api/details/ppt-to-pdf
- 接口 Markdown：https://www.gugudata.com/api/details/ppt-to-pdf/llm.md

关键请求参数：

| 参数 | 必填 | 类型 | 默认值 | 说明 | 来源与传递 |
| --- | --- | --- | --- | --- | --- |
| `file` | 是 | `string/binary` | - | PPT 文件，支持 .ppt 和 .pptx 格式 | 文件或图片来自用户上传、公开 URL 或上一轮转换结果 |
| `storage` | 否 | `string` | public | 文件存储方式，可选 public 或 private。默认 public 返回公开下载地址；private 存入私有存储，返回 file_id，需生成短期下载链接后下载。 | 由用户输入、业务筛选条件或上一轮接口结果确定。 |

### PPT 转高精度图片

- 业务角色：PPT 转图片
- 调用阶段：转换输出
- 接口地址：`POST https://api.gugudata.com/imagerecognition/ppt-to-images`
- 产出用途：用于 PPT 转高精度图片。
- 参数来源：文件或图片来自用户上传、公开 URL 或上一轮转换结果；URL 或域名由用户提供，调用前需要确认协议、跳转和可访问性
- 接口详情页：https://www.gugudata.com/api/details/ppt-to-images
- 接口 Markdown：https://www.gugudata.com/api/details/ppt-to-images/llm.md

关键请求参数：

| 参数 | 必填 | 类型 | 默认值 | 说明 | 来源与传递 |
| --- | --- | --- | --- | --- | --- |
| `file` | 是 | `string/binary` | - | PPT 文件，支持 .ppt 和 .pptx 格式 | 文件或图片来自用户上传、公开 URL 或上一轮转换结果 |
| `url` | 否 | `string` | - | 不传递 PPT 文件流，可直接传递可访问的 PPT 文件地址 | URL 或域名由用户提供，调用前需要确认协议、跳转和可访问性 |
| `scale_factor` | 否 | `number` | 1 | 图片导出缩放因子，默认为 1，最大为 4 倍高清模式 | 由用户输入、业务筛选条件或上一轮接口结果确定。 |
| `storage` | 否 | `string` | public | 文件存储方式，可选 public 或 private。默认 public 返回公开下载地址；private 存入私有存储，返回 file_id，需生成短期下载链接后下载。 | 由用户输入、业务筛选条件或上一轮接口结果确定。 |

### 通用图片文件流 OCR 到文本

- 业务角色：图片流 OCR
- 调用阶段：识别输入
- 接口地址：`POST https://api.gugudata.com/imagerecognition/imagestreamocr`
- 产出用途：用于通用图片文件流 OCR 到文本。
- 参数来源：文件或图片来自用户上传、公开 URL 或上一轮转换结果
- 接口详情页：https://www.gugudata.com/api/details/imagestreamocr
- 接口 Markdown：https://www.gugudata.com/api/details/imagestreamocr/llm.md

关键请求参数：

| 参数 | 必填 | 类型 | 默认值 | 说明 | 来源与传递 |
| --- | --- | --- | --- | --- | --- |
| `imagefile` | 是 | `string/binary` | - | 通过 multipart/form-data 上传的图片文件字段，字段名为 imagefile。 | 文件或图片来自用户上传、公开 URL 或上一轮转换结果 |

### 通用图片地址 OCR 到文本

- 业务角色：图片地址 OCR
- 调用阶段：识别输入
- 接口地址：`POST https://api.gugudata.com/imagerecognition/ocr`
- 产出用途：用于通用图片地址 OCR 到文本。
- 参数来源：URL 或域名由用户提供，调用前需要确认协议、跳转和可访问性；文件或图片来自用户上传、公开 URL 或上一轮转换结果
- 接口详情页：https://www.gugudata.com/api/details/ocr
- 接口 Markdown：https://www.gugudata.com/api/details/ocr/llm.md

关键请求参数：

| 参数 | 必填 | 类型 | 默认值 | 说明 | 来源与传递 |
| --- | --- | --- | --- | --- | --- |
| `imageurl` | 否 | `string` | YOUR_VALUE | 图片 URL 地址，与图标 Base64 编码选其一进行传参 | URL 或域名由用户提供，调用前需要确认协议、跳转和可访问性 |
| `imagebase64` | 否 | `string` | YOUR_VALUE | 图片 Base64 编码，与图标 URL 地址选其一进行传参 | 文件或图片来自用户上传、公开 URL 或上一轮转换结果 |

### 通用图片地址 OCR 到 Word

- 业务角色：图片 OCR 到 Word
- 调用阶段：转换输出
- 接口地址：`POST https://api.gugudata.com/imagerecognition/ocr2word`
- 产出用途：用于图片地址 OCR 到 Word。
- 参数来源：URL 或域名由用户提供，调用前需要确认协议、跳转和可访问性；文件或图片来自用户上传、公开 URL 或上一轮转换结果
- 接口详情页：https://www.gugudata.com/api/details/ocr2word
- 接口 Markdown：https://www.gugudata.com/api/details/ocr2word/llm.md

关键请求参数：

| 参数 | 必填 | 类型 | 默认值 | 说明 | 来源与传递 |
| --- | --- | --- | --- | --- | --- |
| `imageurl` | 否 | `string` | YOUR_VALUE | 图片 URL 地址，与图标 Base64 编码选其一进行传参 | URL 或域名由用户提供，调用前需要确认协议、跳转和可访问性 |
| `imagebase64` | 否 | `string` | YOUR_VALUE | 图片 Base64 编码，与图标 URL 地址选其一进行传参 | 文件或图片来自用户上传、公开 URL 或上一轮转换结果 |

### 图片压缩与尺寸优化

- 业务角色：图片压缩
- 调用阶段：图片处理
- 接口地址：`POST https://api.gugudata.com/ai/image-compress`
- 产出用途：用于图片压缩与尺寸优化。
- 参数来源：文件或图片来自用户上传、公开 URL 或上一轮转换结果；URL 或域名由用户提供，调用前需要确认协议、跳转和可访问性
- 接口详情页：https://www.gugudata.com/api/details/image-compress
- 接口 Markdown：https://www.gugudata.com/api/details/image-compress/llm.md

关键请求参数：

| 参数 | 必填 | 类型 | 默认值 | 说明 | 来源与传递 |
| --- | --- | --- | --- | --- | --- |
| `image_file` | 否 | `string/binary` | - | 上传的图片文件，支持 JPG / JPEG / PNG / GIF / WEBP / BMP，与 image_url 二选一必填 | 文件或图片来自用户上传、公开 URL 或上一轮转换结果 |
| `image_url` | 否 | `string` | - | 网络图片 URL，与 image_file 二选一必填，需为可直接访问的 HTTP/HTTPS 链接 | URL 或域名由用户提供，调用前需要确认协议、跳转和可访问性 |
| `targetWidth` | 否 | `integer` | - | 目标宽度（像素），与 targetHeight 组合使用时按照最长边等比缩放；不传则不以此为约束 | 由用户输入、业务筛选条件或上一轮接口结果确定。 |
| `targetHeight` | 否 | `integer` | - | 目标高度（像素），与 targetWidth 组合使用时按照最长边等比缩放；不传则不以此为约束 | 由用户输入、业务筛选条件或上一轮接口结果确定。 |
| `maxWidth` | 否 | `integer` | - | 最大宽度（像素），只限制不超过该宽度并保持长宽比；当未显式传递任何尺寸参数且图片特别大时，服务会自动使用 1920 作为默认上限 | 由用户输入、业务筛选条件或上一轮接口结果确定。 |
| `maxHeight` | 否 | `integer` | - | 最大高度（像素），只限制不超过该高度并保持长宽比；当未显式传递任何尺寸参数且图片特别大时，服务会自动使用 1920 作为默认上限 | 由用户输入、业务筛选条件或上一轮接口结果确定。 |
| `quality` | 否 | `integer` | 85 | JPEG 压缩质量，取值范围 1-95，数值越低压缩越厉害，推荐在 60-90 之间；PNG 等无损格式将使用内部优化策略忽略该参数 | 由用户输入、业务筛选条件或上一轮接口结果确定。 |
| `format` | 否 | `string` | - | 输出图片格式，可选值：jpeg、png 等；不传则保持原图格式（对于部分不常见格式会自动转换为 JPEG） | 由用户输入、业务筛选条件或上一轮接口结果确定。 |

## 数据校验与使用边界

- 转换前确认文件格式、大小限制、页数和目标格式。
- OCR、格式转换和内容抽取可能受扫描质量、字体、版式和图片清晰度影响。
- 合同、财务、法律等重要文档需要人工复核。

## 输出建议

- 输出文档处理结果时说明原始格式、目标格式、页数和失败项。
- 对批量任务给出成功、失败、需人工处理的清单。
- 对摘要或抽取内容保留原文件链接或文件名以便追溯。

## 常见问题

- 问：什么情况下应该使用这个 Skill？ 答：当用户提出的目标需要多个咕咕数据公开 API 组合完成，而不是只查询一个接口时，优先阅读这个 Skill。
- 问：这个 Skill 是否需要单独购买？ 答：不需要。Skill 文档只负责业务流程和接口选型，具体接口购买、价格和账号权益仍以接口详情页为准。
- 问：Agent 应该怎样使用这个 Skill？ 答：Agent 应先阅读 SKILL.md，确认业务场景和推荐工作流，再进入接口详情页核对参数、响应字段、价格和调用示例。
- 问：调用接口前需要先核对什么？ 答：需要核对业务对象、地区、时间范围、输入格式、必填参数、返回字段、购买状态和接口详情页中的限制说明。
- 问：文档转换与文件处理 Skill 会替代接口文档吗？ 答：不会。Skill 负责说明业务组合和调用顺序，接口参数、响应结构、计费和购买入口仍以接口详情页为准。