Parse 的旋钮很多。这一页是一张地图：它说明一次解析请求是怎么组织的，并逐个记录你能设的选项。

逐字段的完整参考见 Parse API 参考。要控制解析任务返回什么，见取回结果。

请求结构

每个 Parse 请求都是一个 JSON 对象。只有三个字段是必填 —— 其余全部可选：

{
  // --- Required ---
  "file_id": "<file_id>",       // or "source_url" — exactly one is required
  "tier": "agentic",            // fast | cost_effective | agentic | agentic_plus
  "version": "latest",          // dated version string or "latest"

  // --- Optional ---
  "input_options": { /* file-type-specific hints */ },
  "processing_options": { /* how Parse processes the document */ },
  "agentic_options": { /* configures the agentic models */ },
  "output_options": { /* shape of what Parse returns */ },

  "crop_box": { /* page-level crop */ },
  "page_ranges": { /* parse specific pages only */ },
  "disable_cache": false,
  "processing_control": { /* timeouts and fail modes */ },
  "webhook_configurations": [ /* push results to a URL */ ],
  "user_metadata": { /* key/value tags you attach to this job */ }
}

最简单的合法请求就是这三个字段 —— 其余部分等你需要时再加。

注意： expand 并不属于解析请求体。它是 GET 结果端点上的查询参数，决定取回哪些字段。SDK 会替你处理这件事 —— 当你给 client.parsing.parse() 传 expand=["markdown"]，SDK 会提交任务、轮询到完成，再用正确的 expand 取值去取结果。若你直连 REST API，见取回结果。

X 该在哪里配？

我想做的…	该设什么
只解析指定页	page_ranges.target_pages （顶层）
从每一页去掉页眉页脚	crop_box （顶层）
强制全新解析（不走缓存）	disable_cache: true （顶层）
设定任务超时上限	processing_control.timeouts.base_in_seconds （顶层）
把结果推送到 webhook	webhook_configurations （顶层）
用自定义元数据标记任务	user_metadata （顶层）
设置 OCR 语言	processing_options.ocr_parameters.languages
去掉水印文字	output_options.watermark_handling
开启图表解析	processing_options.specialized_chart_parsing
按复杂度自动路由页面	processing_options.cost_optimizer.enable
为每页给解析质量打分	processing_options.confidence_score_effort
处理表单字段、取值与复选框状态	processing_options.forms
用自定义提示词引导	agentic_options.custom_prompt
要 HTML 表格而不是 markdown	output_options.markdown.tables.output_tables_as_markdown: false
把表格导出为 XLSX	output_options.tables_as_spreadsheet.enable
取得逐页截图	output_options.images_to_save: ["screenshot"]
保留空间版面	output_options.spatial_text
取得词 / 行 / 单元格边界框	output_options.granular_bboxes
提取 Word 的修订记录与批注	output_options.markdown.annotate_revisions
归属到印刷的法条行号	output_options.markdown.annotate_line_numbers
控制取回哪些内容	expand 查询参数，在 GET 结果端点上 — see Retrieving Results

---

输入选项

控制 Parse 怎么读你的文档 —— 页范围、裁剪框、按文件类型的控件，以及缓存行为。

页范围

只解析你需要的页。省下的每一页都是不用付钱的一页。

API 键：page_ranges —— 顶层。

• max_pages（integer）从第 1 页起，最多解析多少页
• target_pages（string）逗号分隔的页号与范围（从 1 开始），例如 "1,3,5-10"

从 v1 迁移过来的注意：编号变了

v2 使用从 1 开始的页号。第一页是 1，不是 0。

{ "page_ranges": { "max_pages": 5 } }
{ "page_ranges": { "target_pages": "1,3,7-12" } }

裁剪框

从每一页去掉重复出现的页眉、页脚与页边装订区。四个数字（0.0–1.0），各表示从那条边去掉的比例。

API 键：crop_box —— 顶层。

{ "crop_box": { "top": 0.1, "bottom": 0.15 } }

这是几何裁剪，不是内容过滤。如果装订区在页与页之间会移动，请改用基于内容的忽略规则。

缓存控制

Parse 默认会缓存完全相同的请求。任何解析选项的改动都会自动使缓存失效。

API 键：disable_cache —— 顶层布尔值。

{ "disable_cache": true }

只在做基准测试、调试或验证版本固定时才关闭。

HTML 页面

API 键：input_options.html。

Parse 会遍历 DOM、抽出可见内容并产出干净的 markdown。下面这些控件用来去掉不该出现在输出里的噪声：

• make_all_elements_visible —— 把被 CSS 隐藏的内容强制变为可见。当文档部分藏在 display: none、visibility: hidden 或由 JavaScript 驱动的 UI 状态之后时很有用。
• remove_navigation_elements —— 去掉菜单、面包屑、侧栏导航等非正文的装订区。解析真实网页（而非手工拼出的 HTML 文档）时最有用。
• remove_fixed_elements —— 去掉吸顶页眉、浮动侧栏等固定定位的 UI。

{
  "input_options": {
    "html": {
      "make_all_elements_visible": true,
      "remove_navigation_elements": true,
      "remove_fixed_elements": true
    }
  }
}

电子表格（XLSX、CSV）

API 键：input_options.spreadsheet。

Parse 能处理版式不是干净矩形表格的电子表格 —— 一个 sheet 里纵向堆叠多张逻辑表、公式带陈旧的缓存值等。

• detect_sub_tables_in_sheets —— 在单个 sheet 内找出并抽出子表。如果你的表格里是三张竖排小表、中间用空行隔开，Parse 会把它们各自识别为独立的表，而不是合并成一张。
• force_formula_computation_in_sheets —— 重算公式单元格，而不是用缓存值。文件被编辑过却从未重算、或你在解析一份含占位值的模板时应当开启。在公式密集的 sheet 上会拖慢解析。

{
  "input_options": {
    "spreadsheet": {
      "detect_sub_tables_in_sheets": true,
      "force_formula_computation_in_sheets": true
    }
  }
}

演示文稿（PPTX、Keynote）

API 键：input_options.presentation。

演讲者备注默认就会被抽取 —— 请求 expand=["metadata"] 以在逐页幻灯片的元数据里取回它们。

• include_hidden_slides —— 设为 true 可把隐藏的 PPTX 幻灯片也纳入输出。只作用于 PPTX 文件。省略或 false 则跳过隐藏页。
• out_of_bounds_content —— 抽取位于可见幻灯片边界之外的内容。演讲者常把备注、草稿文字或参考图放在可见区域之外。
• skip_embedded_data —— 跳过内嵌图表数据的抽取。若你只需要幻灯片文字、而图表数据抽取在拖慢你，就设为 true。

{
  "input_options": {
    "presentation": {
      "include_hidden_slides": true,
      "out_of_bounds_content": true,
      "skip_embedded_data": false
    }
  }
}

图片（相机拍摄的照片）

API 键：input_options.image。

拍摄下来的文档照片 —— 桌上拍到的小票、用手机抢拍的表单 —— 传过来时是歪的、周围带着背景、光照也不匀。Parse 可以在解析前把这些收拾干净：

• camera_photo_correction —— 在照片里检测文档边界、裁剪出来、做透视校正，并抚平不匀的光照与阴影，让这一页像平面扫描件一样被解析。作用于 JPEG、PNG、WebP 与 HEIC/HEIF 输入（iPhone 相机的默认格式）。检测策略是保守的：本来就干净如扫描件或截图的图片不会被改动，因此在混合图片批次上开启是安全的。

{
  "input_options": {
    "image": {
      "camera_photo_correction": true
    }
  }
}

PDF 文档

API 键：input_options.pdf —— 有哪些 PDF 专有选项，见 API 参考。

---

输出选项

决定 Parse 返回什么。 同一个任务可以产出多种格式。

我想要…	用
给 LLM 的干净文本	Markdown（默认）
保留空白的版面	Spatial text
可下载的 XLSX 表格	Tables as spreadsheet
内嵌图片、截图与版面裁剪图	Image assets
用于引用的印刷页号	Printed page numbers
以结构化数据给出修订记录与批注	Revision tracking
把印刷的法条行号作为 markdown 偏移	Printed line-number attribution
任一分档文档的 PDF 副本	Exported PDF
用于高亮与落地的词 / 行 / 单元格边界框	Granular bounding boxes
把结果推送到我的服务器	Webhooks

Markdown 输出选项

API 键：output_options.markdown。

症状	旋钮
下游需要 HTML 表格	output_tables_as_markdown: false
表格跨页	merge_continued_tables: true
图片被转写成文字而不是被引用	inline_images: true
想在 markdown 里保留链接目标	annotate_links: true
文档含修订记录或批注	annotate_revisions: true
法律文件在页边印有行号	annotate_line_numbers: true
表格单元格里的空白	compact_markdown_tables: true
单元格含多行内容	`markdown_table_multiline_separator: "

{
  "output_options": {
    "markdown": {
      "annotate_links": true,
      "inline_images": true,
      "tables": { "merge_continued_tables": true, "output_tables_as_markdown": false }
    }
  }
}

修订跟踪

把 Word 风格的修订记录与审阅者批注连同解析内容一起、作为结构化数据抽出来 —— 改了什么、谁改的，以及它在页面与 markdown 里的位置。

API 键：output_options.markdown.annotate_revisions。通过 expand=["items"] 取回。

{ "output_options": { "markdown": { "annotate_revisions": true } } }

它对含修订记录或批注的 Word 文档生效，也对从 Word 导出/打印、且能看到这些标记的 PDF 生效 —— 包括其扫描件。非英语版 Word 产生的修订气泡同样能识别。

开启后，items 结果里的每一页都可以带一个 revisions 数组。每条修订都有一个类型（inserted、deleted、formatted、moved_from、moved_to 或 comment）、它所作用的目标文本、修订或批注内容、可得时的作者，目标文本与印刷修订气泡各自的边界框，以及把目标连到该页最终 markdown 的字符偏移。完整的响应形态见 items 页中的 revisions。

在 Parse playground 里，抽出的修订会出现在一次运行之后的 Revisions 标签中。

**档位限制：**修订依附于 items 结果，而 fast 没有 items。

印刷行号归属

检出法律文件左侧页边槽里印刷的行号，移除这些被检出的标记，并返回它们在最终页 markdown 中的位置。

API 键：output_options.markdown.annotate_line_numbers。通过 expand=["markdown"] 取回。

{ "output_options": { "markdown": { "annotate_line_numbers": true } } }

开启后，每一页 markdown 都可以带一个 line_numbers 数组。每个条目含印刷的 line_number，以及一个半开区间 [start_index, end_index)，用于指明该页最终 markdown 中对应的那一行。没有可靠映射到源行的页面会省略该数组。响应形态见 markdown 页上的行号。

只有印在物理左侧页边槽里的数字才被当作源坐标处理。有序列表、表格列、章节编号与目录标记仍算作内容。

**档位限制：**印刷行号归属在 fast 上不可用。

空间文本

用空白字符保留视觉位置。适合表单、CAD 图纸、多栏版式与收据。

API 键：output_options.spatial_text。通过 expand=["text"] 取回。

开关：preserve_layout_alignment_across_pages、preserve_very_small_text、do_not_unroll_columns。

表格转电子表格

生成一个 XLSX 文件 —— 每张表一个 sheet。

API 键：output_options.tables_as_spreadsheet。通过 expand=["xlsx_content_metadata"] 取回。

{ "output_options": { "tables_as_spreadsheet": { "enable": true } } }

图片资源

API 键：output_options.images_to_save —— 枚举数组："screenshot"、"embedded"、"layout"。通过 expand=["images_content_metadata"] 取回。

{ "output_options": { "images_to_save": ["screenshot", "embedded"] } }

印刷页号

API 键：output_options.extract_printed_page_number（单数形式）。通过 expand=["metadata"] 取回。

水印

在版本 2026-09-28 及之后，模型会挑出横盖在页面上的水印文字（CONFIDENTIAL、DRAFT、公司名等），并把它作为该页 metadata 里的 watermark 字段返回。通过 expand=["metadata"] 取回。一页上有多个不同水印时用 | 拼接，没有水印的页则不含 watermark 字段。

output_options.watermark_handling 决定这段文字在该页 markdown 里怎么处理。默认值 "move_to_end" 把它作为页面的最后一个块保留，"move_to_start" 放到最前，"remove" 直接丢掉：

{ "output_options": { "watermark_handling": "remove" } }

text 输出来自 PDF 的文本层，因此只有当水印在文本层里本就独占一行时，才会跟随同样的选择。印在正文一行中间的水印仍会留在 text 输出里。

这对扫描页与纯图片页同样有效，因为模型是从页面图像上读出水印的。processing_options.ignore.ignore_diagonal_text 则不同：它丢掉的是 PDF 文本层里的旋转文字，所以只有当水印确实是旋转文本时它才管用。

**档位限制：**版本 2026-09-28 及之后的 cost_effective、agentic 与 agentic_plus。在 fast 与更早版本上会被忽略。

导出的 PDF

始终生成 —— 无需任何输入配置。通过 expand=["output_pdf_content_metadata"] 取回。

细粒度边界框

在 Parse 本就返回的条目级版面框之外，再取得逐词、逐行与逐表格单元格的边界框。当你需要在源文档上高亮单个词或单行（例如一个 PDF 查看器要高亮引用确切指向的那段），或要把抽取出的答案落到字形级别时，就用它。

API 键：output_options.granular_bboxes —— 从 "word"、"line"、"cell" 中取一个或多个的数组。空数组（默认）表示关闭细粒度框，只返回条目级的版面框。

{ "output_options": { "granular_bboxes": ["word", "line", "cell"] } }

当 granular_bboxes 非空时，Parse 会写出一份 grounded-items 的 JSONL 边车文件（每页一行），并在结果里带上它的预签名下载地址。你在 expand 里不需要额外加任何东西 —— 响应形态与 JSONL schema 见 取回结果中的 grounded items。

完整走查（请求、取边车文件、遍历逐词/逐行/逐单元格的落地数据）见细粒度边界框示例。

档位限制：fast 上不可用（没有条目级版面，细粒度落地也就无所依附）。

webhook 配置

用推送代替轮询。适合大型 PDF、批量流水线，或结果要交给另一个服务的场合。

API 键：webhook_configurations —— 顶层数组。

{
  "webhook_configurations": [{
    "webhook_url": "https://example.com/webhook",
    "webhook_events": ["parse.success"],
    "webhook_headers": { "Authorization": "Bearer your-token" }
  }]
}

**安全：**使用 HTTPS，把认证 token 放在 webhook_headers 里（而不是查询参数），在你的处理函数里校验调用方，绝不让不可信的用户控制 webhook_url。

用户元数据

API 键：user_metadata —— 顶层 dict[str, str]。可以给任务附上任意的键值标记；在任务响应上原样返回。不可用于检索。最多 8 组键值对、键 24 字符、值 64 字符、合计 512 字节。

{ "user_metadata": { "owner": "jerry", "team": "research" } }

---

处理选项

控制 Parse 怎么处理你的文档 —— 旗舰能力、调优旋钮与生产控件。

成本优化器

**只在真正需要的页上付 premium 价。**它把每一页自动路由到合适的档位：简单页 → cost_effective，复杂页 → 你所选的档位。两组并行运行。

API 键：processing_options.cost_optimizer。仅在 agentic 与 agentic_plus 上可用。

{ "processing_options": { "cost_optimizer": { "enable": true } } }

**何时用：**多数页是正文、少数复杂的文档。**何时别用：**每一页都表格密集、你已经用着 cost_effective/fast，或者你需要完全可复现。

请求 expand=["metadata"] 可以看到哪些页做了成本优化（逐页的 cost_optimized: true/false）。

专门的图表解析

把图表数据抽成结构化表格 —— 柱高、折线取值、饼图占比。

API 键：processing_options.specialized_chart_parsing —— 枚举："efficient"、"agentic"、"agentic_plus"。Agentic Plus 默认开启。 fast 上不可用。

{ "processing_options": { "specialized_chart_parsing": "agentic_plus" } }

通过 expand=["items"] 取回图表数据。见图表解析教程。

置信度得分（高强度）

**知道每一页的解析结果有多可信。**设 confidence_score_effort: "high" 后，LlamaParse 会给出更准的解析质量评估：结果元数据里每页的 confidence（0→1）反映的是这轮高强度评估，而整份文档也会在元数据的 document 对象里拿到一个汇总 confidence 及其拆分（最差页得分、按标签的计数）。

API 键：processing_options.confidence_score_effort —— 枚举："high"。省略该选项即为标准打分（默认）。高强度打分额外收 每页 5 credit。

{ "processing_options": { "confidence_score_effort": "high" } }

请求 expand=["metadata"] 以读取逐页与文档级的得分。

表单增强输出（Beta）

**把每个表单页作为结构化 JSON 拿到。**设 forms: "enrich" 后，Parse 会在被判定为表单的页上额外跑一轮表单分析，返回其小节、带标签及其填写值的字段与复选框状态、可填写网格，以及每个字段的边界框 —— 与常规的 markdown 和 items 输出并列。

API 键：processing_options.forms —— 枚举："enrich"、"default"。省略该选项或传 "default" 即标准解析、不跑额外一轮。fast 上不可用。含表单的页每页加 10 credit。

{ "processing_options": { "forms": "enrich" } }

通过 expand=["forms"] 取回这份 JSON，或用 expand=["forms_content_metadata"] 取其预签名下载地址。响应形态与遍历方式见表单增强输出示例。

自定义提示词

用自然语言指令引导解析器 —— 聚焦特定内容、保留某种格式、补充文档背景。

API 键：agentic_options.custom_prompt（不是 processing_options）。在 cost_effective、agentic、agentic_plus 上可用。fast 上不可用。

{ "agentic_options": { "custom_prompt": "This is a financial report. Preserve all currency symbols." } }

**技巧：**写得具体、点明文档类型、说明要跳过什么、指明输出格式、保持简短（两三句）。若要用 schema 保证结构化抽取的形状，请改用 LlamaExtract。

跳过特定内容

API 键：processing_options.ignore。

开关	跳过什么
ignore_diagonal_text	PDF 文本层里的旋转文字，例如斜向水印。扫描页上的水印见水印
ignore_text_in_image	内嵌图片里低质量的 OCR 文字
ignore_hidden_text	白底白字或被 CSS 隐藏的文字

OCR 语言

API 键：processing_options.ocr_parameters.languages。只影响从图片里读出的文字 —— 原生数字 PDF 里的文本会被直接读取。

{ "processing_options": { "ocr_parameters": { "languages": ["en", "fr", "de"] } } }

表格抽取调优

开关	作用
aggressive_table_extraction	更努力地寻找表格（可能带来误检）
disable_heuristics	关掉带框线表格抽取与超长表格的自适应处理

超时与失败条件

API 键：processing_control —— 顶层（不在 processing_options 之下）。

超时：base_in_seconds +（extra_time_per_page_in_seconds × 页数）。

失败条件：allowed_page_failure_ratio、fail_on_image_extraction_error、fail_on_image_ocr_error、fail_on_markdown_reconstruction_error、fail_on_buggy_font。

{
  "processing_control": {
    "timeouts": { "base_in_seconds": 300, "extra_time_per_page_in_seconds": 30 },
    "job_failure_conditions": { "allowed_page_failure_ratio": 0.05 }
  }
}

---

另请参阅

• 档位 —— credit 开销、档位对比与版本固定
• 取回结果 —— expand 参数与能取回什么
• 配方 —— 可复制粘贴的片段
• API 参考 —— 逐字段的完整列表