HTML 转 PDF

网页转 PDF，支持公开或私有存储

POST /imagerecognition/html2pdf

业务说明

超高性能转换效率；

支持将传递的 HTML 转换为 PDF，支持转换 HTML 中的 CSS 格式；

支持传递网站 URL，直接转换页面成对应的 PDF 文件；

支持公开存储和私有存储，私有模式通过短期下载链接访问；

接口服务多节点部署；

围绕“HTML/URL 转 PDF”提供标准化能力，便于快速接入现有业务；

适合将“HTML/URL 转 PDF”结果接入业务系统、后台工具和自动化流程；

适合合同、票据、课件和归档文件的自动化处理；

鉴权：需要 AppKey，使用本操作声明的鉴权位置。

请求参数

参数	位置	类型	必填	真实默认值	说明
appkey	query	string	否	无	付费后获取的 APPKEY
appkey	body / application/json	string	否	无	付费后获取的 APPKEY
type	body / application/json	string	是	无	可选参数为 HTML 或 URL（注意，当类型为 URL 时，需要保证页面可以正常请求，我们的接口不解决加密页面、反爬虫页面等不能正常返回 HTML 的页面请求）
content	body / application/json	string	是	无	内容正文，如果 type=HTML，那么传递 HTML 内容；如果 type=URL，那么传递需要存储为 PDF 的站点 URL 即可
landscape	body / application/json	["string", "number", "boolean", "null"]	否	0	控制生成 PDF 是否为横向页面模式，传递 1 控制页面横向渲染模式，默认为 0
showpages	body / application/json	["string", "number", "boolean", "null"]	否	0	控制生成的 PDF 是否在页脚包含页码信息，传递 1 控制页脚生成页码，默认为 0
filename	body / application/json	["string", "null"]	否	无	可选参数，控制生成的文件名称，不需要后缀
storage	body / application/json	["string", "null"]	否	public	文件存储方式，可选 public 或 private。默认 public 返回公开下载地址；private 存入私有存储，返回 file_id，需生成短期下载链接后下载。
appkey	body / application/x-www-form-urlencoded	string	否	无	付费后获取的 APPKEY
type	body / application/x-www-form-urlencoded	string	是	无	可选参数为 HTML 或 URL（注意，当类型为 URL 时，需要保证页面可以正常请求，我们的接口不解决加密页面、反爬虫页面等不能正常返回 HTML 的页面请求）
content	body / application/x-www-form-urlencoded	string	是	无	内容正文，如果 type=HTML，那么传递 HTML 内容；如果 type=URL，那么传递需要存储为 PDF 的站点 URL 即可
landscape	body / application/x-www-form-urlencoded	string	否	0	控制生成 PDF 是否为横向页面模式，传递 1 控制页面横向渲染模式，默认为 0
showpages	body / application/x-www-form-urlencoded	string	否	0	控制生成的 PDF 是否在页脚包含页码信息，传递 1 控制页脚生成页码，默认为 0
filename	body / application/x-www-form-urlencoded	string	否	无	可选参数，控制生成的文件名称，不需要后缀
storage	body / application/x-www-form-urlencoded	string	否	public	文件存储方式，可选 public 或 private。默认 public 返回公开下载地址；private 存入私有存储，返回 file_id，需生成短期下载链接后下载。

独立请求示例

{
  "type": "HTML",
  "content": "<!doctype html><html lang=\"zh-CN\"><meta charset=\"utf-8\"><body><h1>网页归档示例</h1><p>中文与 English 内容。</p></body></html>",
  "landscape": 0,
  "showpages": 1,
  "filename": "网页归档示例",
  "storage": "public"
}

返回契约

HTTP 200：业务码 100 成功。
application/json

{
  "type": "object",
  "properties": {
    "Data": {
      "oneOf": [
        {
          "type": "string",
          "format": "uri",
          "description": "公开存储时返回文件下载地址；私有存储时返回文件引用，可用于生成短期下载链接。"
        },
        {
          "type": "object",
          "properties": {
            "storage": {
              "type": "string",
              "enum": [
                "private"
              ],
              "description": "私有结果固定 private。"
            },
            "file_id": {
              "type": "string",
              "description": "私有文件标识。"
            },
            "file_name": {
              "type": "string",
              "description": "私有输出文件名，含 .pdf 后缀。"
            },
            "content_type": {
              "type": "string",
              "enum": [
                "application/pdf"
              ],
              "description": "私有结果为 application/pdf。"
            },
            "size_bytes": {
              "type": "integer",
              "description": "私有 PDF 字节数。"
            },
            "index": {
              "type": [
                "integer",
                "null"
              ],
              "description": "文件序号；单文件时可为空。"
            }
          },
          "required": [
            "storage",
            "file_id",
            "file_name",
            "content_type",
            "size_bytes",
            "index"
          ],
          "description": "公开存储时返回文件下载地址；私有存储时返回文件引用，可用于生成短期下载链接。"
        }
      ],
      "description": "公开存储时返回文件下载地址；私有存储时返回文件引用，可用于生成短期下载链接。"
    },
    "DataStatus": {
      "type": "object",
      "required": [
        "RequestParameter",
        "StatusCode",
        "StatusDescription",
        "ResponseDateTime",
        "DataTotalCount"
      ],
      "properties": {
        "RequestParameter": {
          "type": "string",
          "description": "真实、可读的业务请求参数；无业务参数时为空，不包含凭据。"
        },
        "StatusCode": {
          "type": "integer"
        },
        "StatusDescription": {
          "type": "string"
        },
        "ResponseDateTime": {
          "type": "string"
        },
        "DataTotalCount": {
          "type": "integer",
          "description": "本次实际返回的记录或动态表格行数。"
        }
      }
    }
  },
  "required": [
    "Data",
    "DataStatus"
  ]
}

HTTP 401：公共鉴权失败；沿用现有公共契约。

HTTP 403：公共权益或额度不足；沿用现有公共契约。

HTTP 404：资源不存在。请求路径不存在。
application/json

{
  "$ref": "#/components/schemas/CommonResponse"
}

HTTP 405：请求方法不允许。当前路径不支持该 HTTP 方法。
application/json

{
  "$ref": "#/components/schemas/CommonResponse"
}

HTTP 415：请求内容类型不支持。上传或请求体的内容类型不符合接口要求。
application/json

{
  "$ref": "#/components/schemas/CommonResponse"
}

HTTP 429：公共频率限制；沿用现有公共契约。

HTTP 502：上游依赖错误。上游依赖服务不可用或返回异常。
application/json

{
  "$ref": "#/components/schemas/CommonResponse"
}

HTTP 400：业务码 501：参数缺失、非法、重复或冲突。
application/json

{
  "type": "object",
  "properties": {
    "DataStatus": {
      "type": "object",
      "required": [
        "RequestParameter",
        "StatusCode",
        "StatusDescription",
        "ResponseDateTime",
        "DataTotalCount"
      ],
      "properties": {
        "RequestParameter": {
          "type": "string",
          "description": "真实、可读的业务请求参数；无业务参数时为空，不包含凭据。"
        },
        "StatusCode": {
          "type": "integer"
        },
        "StatusDescription": {
          "type": "string"
        },
        "ResponseDateTime": {
          "type": "string"
        },
        "DataTotalCount": {
          "type": "integer",
          "description": "本次实际返回的记录或动态表格行数。"
        }
      }
    },
    "Data": {
      "type": "null",
      "description": "公开存储时返回文件下载地址；私有存储时返回文件引用，可用于生成短期下载链接。"
    }
  }
}

HTTP 503：业务码 901：处理、依赖失败或超时。
application/json

{
  "type": "object",
  "properties": {
    "DataStatus": {
      "type": "object",
      "required": [
        "RequestParameter",
        "StatusCode",
        "StatusDescription",
        "ResponseDateTime",
        "DataTotalCount"
      ],
      "properties": {
        "RequestParameter": {
          "type": "string",
          "description": "真实、可读的业务请求参数；无业务参数时为空，不包含凭据。"
        },
        "StatusCode": {
          "type": "integer"
        },
        "StatusDescription": {
          "type": "string"
        },
        "ResponseDateTime": {
          "type": "string"
        },
        "DataTotalCount": {
          "type": "integer",
          "description": "本次实际返回的记录或动态表格行数。"
        }
      }
    },
    "Data": {
      "type": "null",
      "description": "公开存储时返回文件下载地址；私有存储时返回文件引用，可用于生成短期下载链接。"
    }
  }
}

业务状态与 HTTP 状态

业务码	含义	说明
100	成功	HTTP 200；仍应检查业务状态。
501	参数错误	HTTP 400
901	依赖失败	HTTP 503

接口详情：https://www.gugudata.com/api/details/html2pdf
OpenAPI：https://www.gugudata.com/openapi/gugudata.openapi.3.1.json

请求示例代码

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

返回响应

🟢200成功

application/json

业务码 100 成功。

Bodyapplication/json

示例

{
  "Data": "string",
  "DataStatus": {
    "StatusCode": 0,
    "StatusDescription": "string",
    "ResponseDateTime": "string",
    "DataTotalCount": 0
  }
}

🟠400请求参数错误。请求参数缺失、格式错误或参数组合不合法。

🟠401鉴权失败。缺少 appkey 或 appkey 无效。

🟠403无权限访问。订单到期、权限不足或接口额度不可用。

🟠404资源不存在。请求路径不存在。

🟠405请求方法不允许。当前路径不支持该 HTTP 方法。

🟠415请求内容类型不支持。上传或请求体的内容类型不符合接口要求。

🟠429请求频率受限。默认情况下，每个接口提供 5 QPS 并发能力，可满足大多数业务场景。超出当前并发能力时，网关可能返回 429 请求频率受限；如需更高吞吐，可按需购买额外 QPS 扩展包，高频调用场景支持白名单接入与独立流控策略。

🔴500服务内部错误。服务端处理异常，请稍后重试。

🔴502上游依赖错误。上游依赖服务不可用或返回异常。

🔴503业务码 901：处理、依赖失败或超时。

业务说明#

请求参数#

独立请求示例#

返回契约#

业务状态与 HTTP 状态#

请求参数

请求示例代码

返回响应

业务说明

请求参数

独立请求示例

返回契约

业务状态与 HTTP 状态