线性化 PDF

PDF4me 线性化 PDF 是一个 REST 重构端点 PDF 用于快速网页浏览。 POST 文件为 Base64 到 /api/v2/LinearizePdf 一个 optimizeProfile以及 API 重新排列其内部对象，以便第一页在其余页面仍在下载时渲染，然后返回线性化结果。 PDF 以原始字节形式。九种配置文件涵盖网页、印刷和压缩。

此端点的作用

需要 PDF 并返回经过重新组织以实现渐进式加载的同一文档：目录信息和第一页资源移至文件开头，因此浏览器或嵌入式查看器几乎可以立即显示第一页，而无需等待整个下载完成。 pages 本身未受影响。非常适合文档门户、CDN 和任何其他用途。 PDF 供应 HTTP。

验证您的身份 API 要求

每一个 PDF4me REST 通话必须包含您的 API 关键在于 Authorization 请求头设置为基本身份验证。请从开发者控制面板获取或轮换您的密钥。

Get your API Key

端点

POST/api/v2/线性化Pdf

邮递员 URLhttps://api.pdf4me.com/api/v2/LinearizePdf

您不容错过的重要事实

该标志是异步的，而不是 IsAsync。

官方示例中异步开关以小写形式发送。 异步，一个 JSON 布尔值。大小写错误的键将被静默忽略，大文件将同步处理。

200 响应是 PDF 自身

主体是原始二进制数据：直接写入到 .pdf 文件。官方示例也处理一个 JSON包装 Base64 采取防御措施，但主要合约是字节。

相同的 pages不同的字节顺序

线性化从不编辑内容。它重新排列内部对象，使第 1 页和文档目录位于文件的最前面，这样就可以在下载完成之前让查看器渲染内容。

HTTP 设置

方法： POST
URL： https://api.pdf4me.com/api/v2/LinearizePdf
内容类型： application/json
Authorization： 基本 <您的 PDF4me API 键>

200响应体是线性化的。 PDF 以原始字节格式：直接保存。202 响应表示异步处理：轮询。 Location URL 和 GET 大约每隔 10 秒（官方样本使用 10 秒间隔，最多重试 10 次），直到 200。

我应该选择哪个优化配置文件？

我们接受九种不同的求职者类型。它们分为三大类，目标各不相同。

家庭概况与目标	简介	它们优化的目标是什么？
网站	`web`， `WebMax`	WebMax 提供渐进式显示和快速的浏览器首页渲染，是目前最强大的网页优化技术。
打印	`Print`， `PrintMax`， `PrintGray`	面向打印的输出；PrintGray 也可转换为灰度打印
压缩	`Compress`， `CompressMax`	文件大小最小；CompressMax 通过增加处理量来获得更大的压缩率。
一般的	`Default`， `Max`	引擎默认设置，以及最高整体优化级别

为了 PDFs 在网站上提供服务，以……开头 web 并逐步提升 WebMax 只有在测试后首页延迟仍然重要的情况下才需要考虑。

API 身体场

范围	必需的	类型	它的作用	例子
`docContent`	Required	string	Base64-encoded bytes of the source PDF.	`JVBERi0xLjcK...`
`docName`	Required	string	Source PDF filename with its .pdf extension.	`document.pdf`
`optimizeProfile`	Required	string	Optimization profile. Allowed values: web, Max, Print, Default, WebMax, PrintMax, PrintGray, Compress, CompressMax. Values are case-sensitive as listed.	`web`
`async`	Optional	boolean	Lowercase JSON boolean. true returns 202 plus a Location URL to poll, for large files. false or omitted returns the linearized PDF directly on 200.	`true`

示例有效载荷

线性化以适应网页浏览

{
 "docContent": "JVBERi0xLjcKJb...",
 "docName": "report.pdf",
 "optimizeProfile": "web"
}

大文件，异步

{
 "docContent": "JVBERi0xLjcKJb...",
 "docName": "catalog-2026.pdf",
 "optimizeProfile": "WebMax",
 "async": true
}

邮递员收款小贴士

Headers

Content-Type: application/json + Authorization: Basic <apiKey>.

Body

raw JSON with docContent, docName, optimizeProfile, and optionally async (lowercase, boolean).

Response

On 200, use "Send and Download": the body is the PDF itself, not JSON.

Async

With async true, copy the Location header from the 202 response into a GET request and poll it every ~10 seconds until 200.

curl 示例

curl -X POST https://api.pdf4me.com/api/v2/LinearizePdf \
 -H "Content-Type: application/json" \
 -H "Authorization: Basic YOUR_API_KEY" \
 -d '{
 "docContent": "'"$(base64 -w 0 report.pdf)"'",
 "docName": "report.pdf",
 "optimizeProfile": "web"
 }' \
 --output linearized.pdf

什么 API 返回？

场地	类型	它包含什么
`200 response body`	Binary (application/pdf)	The linearized PDF as raw bytes. Save it directly. The official samples also handle a JSON-wrapped Base64 fallback, but binary is the primary contract.
`202 Location header`	URL	Async mode only: the polling URL. GET it about every 10 seconds (samples: 10 retries) until it returns 200 with the PDF bytes.
`4xx/5xx response body`	JSON or text	Error details: 400 for malformed Base64 or an unknown optimizeProfile value, 401 for a missing or invalid API key, 500 for server-side processing failures.

代码示例

针对此特定端点的官方可运行示例 language：

常问问题

What is a linearized PDF?+

A PDF whose internal objects are reordered so the first page and its resources sit at the front of the file. A viewer can render page 1 while the rest is still downloading, which is why linearization is also called fast web view.

Does linearization change how the PDF looks?+

No. Pages, text, and images stay identical. Only the internal object order and structure change so browsers and viewers can start rendering before the full file arrives.

Which optimizeProfile should I use for websites?+

Start with web. If load speed matters more than anything else, WebMax applies the most aggressive web optimization. The print and compress profiles target paper output and file size instead of progressive display.

Is the async flag called IsAsync?+

No. The official samples send it as lowercase async, a JSON boolean. Sending true switches the API to 202-plus-polling mode; false or omitting it returns the linearized PDF directly in the response body.

Is the response JSON with a Base64 file inside?+

Normally no: a 200 response body is the linearized PDF as raw bytes, ready to save. The official samples also defensively handle a JSON-wrapped Base64 variant, but the primary contract is binary.

How is this different from Compress PDF?+

Compress PDF exists to shrink file size. Linearize PDF exists to reorder the file for progressive display; the Compress and CompressMax profiles borrow some size reduction, but if pure size is the goal, use the dedicated Compress PDF endpoint.

Does my web server need special support?+

For the full benefit the server should support HTTP byte-range requests, which mainstream web servers and CDNs do by default. The linearized file still opens normally everywhere, even without range support.

为什么要线性化 PDFs 用于网络？

标准 PDF 它将目录信息存储在文件末尾，因此查看器必须先下载几乎所有内容才能渲染第一页。线性化 PDF被定义为以下文件的规范性附件： ISO 32000 规格将该目录和第一页移到最前面，从而实现对目录的增量访问。 HTTP对于文档门户或 CDN这样，原本几秒钟的空白等待时间就会变成第一个页面，而其他页面则会陆续加载。