LlamaParse API v2 指南

本综合指南涵盖了LlamaParse的新版v2 API端点，它引入了结构化配置方法以实现更好的组织和验证。

⚠️ Alpha版本警告: v2端点目前处于alpha测试阶段（v2alpha1），在稳定版发布前可能发生破坏性变更。我们建议进行充分测试，并为开发期间可能的API变更做好准备。

快速入门

基本用法

文件ID解析（推荐）：

curl -X POST \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "existing-file-id",
    "parse_options": {
      "parse_mode": "preset",
      "preset_options": {
        "preset": "scientific"
      }
    }
  }' \
  "https://api.cloud.llamaindex.ai/api/v2alpha1/parse"

URL解析：

curl -X POST \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_url": "https://example.com/document.pdf",
    "parse_options": {
      "parse_mode": "preset",
      "preset_options": {
        "preset": "scientific"
      }
    }
  }' \
  "https://api.cloud.llamaindex.ai/api/v2alpha1/parse/url"

多部分文件上传：

curl -X POST \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" \
  -F "file=@document.pdf" \
  -F 'configuration={
    "parse_options": {
      "parse_mode": "preset",
      "preset_options": {
        "preset": "scientific"
      }
    }
  }' \
  "https://api.cloud.llamaindex.ai/api/v2alpha1/parse/upload"

与v1版本的不同之处

单一配置参数: v2版本使用一个JSON配置字符串，替代了原先70多个独立的表单参数
专用端点: 四个独立的端点用于不同的输入方法 (/, /url, /upload, /base64)
解析模式特定选项：仅显示与所选解析模式相关的可用选项
更优验证: 具有清晰错误信息的结构化JSON模式
层级化组织: 相关设置按逻辑分组

端点详情

v2 提供了四个针对不同输入方法的专用端点：

文件ID解析（推荐）

网址: https://api.cloud.llamaindex.ai/api/v2alpha1/parse
方法: POST
内容类型: application/json
使用场景: 解析已上传的文件

URL解析

网址: https://api.cloud.llamaindex.ai/api/v2alpha1/parse/url
方法: POST
内容类型: application/json
使用场景: 直接从网页URL解析文档

多部分文件上传

网址: https://api.cloud.llamaindex.ai/api/v2alpha1/parse/upload
方法: POST
内容类型: multipart/form-data
使用场景: 客户端应用程序的传统文件上传

Base64 文件上传

网址: https://api.cloud.llamaindex.ai/api/v2alpha1/parse/base64
方法: POST
内容类型: application/json
使用场景: JSON API集成场景中文件采用base64编码

必需请求头: Authorization: Bearer YOUR_API_KEY (所有端点)

选择正确的端点

根据您的使用场景选择合适的端点：

端点	使用场景	输入方法	内容类型
`/`	推荐：解析已上传的文件	文件ID参考	`application/json`
`/url`	直接从网页URL、共享链接或公共文档解析文档	URL 参考	`application/json`
`/upload`	从客户端应用程序、网页表单或文件选择器上传新文件	多部分表单数据	`multipart/form-data`
`/base64`	与JSON API、移动应用集成，或当您拥有base64编码的文件内容时	JSON 中的 Base64 编码文件	`application/json`

主要区别：

URL字段: 仅 /url 端点接受 source_url 和 http_proxy 字段
文件处理: /upload 使用传统文件上传方式, /base64 嵌入内容, / 引用现有文件, /url 远程获取
配置位置: /upload 使用带有 configuration 参数的表单数据，其他方式将配置嵌入到 JSON 主体中

配置结构

配置结构因端点而异，每个端点仅接受与其输入方法相关的参数：

文件ID解析 (`/`) - 推荐

JSON 请求体：

{
  "file_id": "existing-file-id (required)",
  "parse_options": {
    "parse_mode": "preset|parse_with_llm|parse_with_agent|etc.",
    // Mode-specific options
  },
  "webhook_configurations": [...],
  "input_options": {...},
  "crop_box": {...},
  "page_ranges": {...},
  "disable_cache": "boolean (optional)",
  "output_options": {...},
  "processing_control": {...}
}

URL解析 (`/url`)

JSON 请求体：

{
  "source_url": "https://example.com/document.pdf (required)",
  "http_proxy": "https://proxy.example.com (optional)",
  "parse_options": {
    "parse_mode": "preset|parse_with_llm|parse_with_agent|etc.",
    // Mode-specific options
  },
  "webhook_configurations": [...],
  "input_options": {...},
  "crop_box": {...},
  "page_ranges": {...},
  "disable_cache": "boolean (optional)",
  "output_options": {...},
  "processing_control": {...}
}

多部分上传 (`/upload`)

表单参数：

file (必填): 要上传的文档文件
configuration (必填): 包含解析选项的JSON字符串

配置JSON结构：

{
  "parse_options": {
    "parse_mode": "preset|parse_with_llm|parse_with_agent|etc.",
    // Mode-specific options
  },
  "webhook_configurations": [...],
  "input_options": {...},
  "crop_box": {...},
  "page_ranges": {...},
  "disable_cache": "boolean (optional)",
  "output_options": {...},
  "processing_control": {...}
}

Base64上传 (`/base64`)

JSON 请求体：

{
  "base64_file": "base64-encoded-content (required)",
  "filename": "document.pdf (optional)",
  "parse_options": {
    "parse_mode": "preset|parse_with_llm|parse_with_agent|etc.",
    // Mode-specific options
  },
  "webhook_configurations": [...],
  "input_options": {...},
  "crop_box": {...},
  "page_ranges": {...},
  "disable_cache": "boolean (optional)",
  "output_options": {...},
  "processing_control": {...}
}

解析模式

parse_mode 字段决定了文档的处理方式。每种模式都有仅适用于该模式的特定选项。

预设模式 (`"preset"`)

最佳适用场景：使用针对特定文档类型优化的预定义配置快速完成设置。

可用预设：

"invoice" / "invoice-v-1" - 针对发票和收据进行优化
"scientific" / "scientific-v-1" - 适用于科学论文和研究文档
"forms" / "forms-v-1" - 用于表单和问卷
"technicalDocumentation" / "technicalDocumentation-v-1" - 适用于带原理图的技术文档
"slides" - 用于演示幻灯片
"formsBboxExperimental" - 使用边界框进行实验性表单解析

配置：

{
  "parse_options": {
    "parse_mode": "preset",
    "preset_options": {
      "preset": "scientific",
      "ocr_parameters": {
        "languages": ["en", "es"]
      }
    }
  }
}

不使用AI解析 (`"parse_without_ai"`)

最适合: 从布局简单的文档中快速提取文本。

工作原理: 直接提取文本而不进行AI重构。最快的选项但不支持markdown格式。

配置：

{
  "parse_options": {
    "parse_mode": "parse_without_ai",
    "parse_without_ai_options": {
      "ignore": {
        "ignore_diagonal_text": true,
        "ignore_text_in_image": false
      },
      "ocr_parameters": {
        "languages": ["en"]
      }
    }
  }
}

使用LLM解析 (`"parse_with_llm"`)

最适合: 包含混合内容（文本、表格、图像）且需要结构化输出的文档。

工作原理: 使用大型语言模型从提取的文本和图像中重建文档结构。

配置：

{
  "parse_options": {
    "parse_mode": "parse_with_llm",
    "parse_with_llm_options": {
      "model": "gpt-4o",
      "prompts": {
        "user_prompt": "Extract key financial information",
        "system_prompt_append": "Focus on tables and charts"
      },
      "ignore": {
        "ignore_diagonal_text": false,
        "ignore_text_in_image": false
      },
      "ocr_parameters": {
        "languages": ["en", "fr"]
      }
    }
  }
}

使用外部提供商解析 (`"parse_with_external_provider"`)

最适合: 使用您自己的多模态模型API密钥或特定的Azure部署。

工作原理：将页面截图发送至外部视觉模型进行处理。

配置：

{
  "parse_options": {
    "parse_mode": "parse_with_external_provider",
    "parse_with_external_provider_options": {
      "model": "openai-gpt4o",
      "vendor_multimodal_api_key": "sk-proj-...",
      "prompts": {
        "user_prompt": "Extract structured data"
      },
      "azure_openai": {
        "deployment_name": "gpt-4-vision",
        "endpoint": "https://myresource.openai.azure.com/",
        "api_key": "your-key",
        "api_version": "2024-02-01"
      }
    }
  }
}

支持的模型：

openai-gpt4o (default)
openai-gpt-4o-mini
openai-gpt-4-1-nano
openai-gpt-4-1-mini
openai-gpt-4-1
anthropic-sonnet-3.5 (deprecated)
anthropic-sonnet-3.7
anthropic-sonnet-4.0
anthropic-sonnet-4.5
anthropic-haiku-4.5
gemini-2.0-flash
gemini-2.5-flash
gemini-2.5-pro
gemini-1.5-flash (discontinued)
gemini-1.5-pro (discontinued)

使用智能体解析 (`"parse_with_agent"`)

最适合：需要最高精度的复杂文档（财务报告、密集布局）。

工作原理: 采用智能体推理循环，结合文本与视觉分析以实现最高保真度。

配置：

{
  "parse_options": {
    "parse_mode": "parse_with_agent",
    "parse_with_agent_options": {
      "model": "anthropic-sonnet-4.0",
      "ignore": {
        "ignore_diagonal_text": false
      },
      "ocr_parameters": {
        "languages": ["en"]
      },
      "prompts": {
        "user_prompt": "Preserve all table structure and equations"
      }
    }
  }
}

使用布局智能体解析 (`"parse_with_layout_agent"`)

最适合：对精确定位有要求的文档（视觉引用、密集布局）。

工作原理: 使用针对布局保持优化的视觉语言模型。

配置：

{
  "parse_options": {
    "parse_mode": "parse_with_layout_agent",
    "parse_with_layout_agent_options": {}
  }
}

自动模式 (`"auto"`)

最适合: 基于文档内容动态调整的解析功能。

工作原理: 根据检测到的内容类型自动选择解析策略。

配置：

{
  "parse_options": {
    "parse_mode": "auto",
    "auto_options": {
      "configuration_json": "{}",
      "trigger_on": {
        "image": true,
        "table": true,
        "text": "financial",
        "regexp": "\\$[0-9,]+\\.[0-9]{2}"
      },
      "ignore": {
        "ignore_diagonal_text": false
      },
      "ocr_parameters": {
        "languages": ["en"]
      }
    }
  }
}

输入选项

配置不同文件类型的处理方式：

{
  "input_options": {
    "html": {
      "make_all_elements_visible": true,
      "remove_fixed_elements": true,
      "remove_navigation_elements": true
    },
    "pdf": {
      "disable_image_extraction": false
    },
    "spreadsheet": {
      "detect_sub_tables_in_sheets": true,
      "force_formula_computation_in_sheets": true
    },
    "presentation": {
      "out_of_bounds_content": true,
    }
  }
}

HTML 选项

make_all_elements_visible: 在解析过程中强制显示隐藏元素
remove_fixed_elements: 移除固定定位元素（页眉、侧边栏）
remove_navigation_elements: 移除导航菜单

PDF选项

disable_image_extraction: 跳过从PDF中提取嵌入图像

电子表格选项

detect_sub_tables_in_sheets: 查找并提取电子表格单元格内的子表格
force_formula_computation_in_sheets: 强制重新计算包含公式的电子表格单元格

演示选项

out_of_bounds_content: 提取演示文稿中超出边界的内容

页面范围

控制要处理的页面：

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

max_pages: 最大处理页数
target_pages: 使用基于1的索引指定具体页面（例如，“1,3,5-10”表示第1页、第3页以及第5至10页）

重要提示: v2版本使用基于1的页码索引，与v1版本使用的基于0的索引方式不同。

裁剪框

定义每个页面中要解析的特定区域：

{
  "crop_box": {
    "top": 0.1,
    "right": 0.1,
    "bottom": 0.1,
    "left": 0.1
  }
}

数值是页面尺寸的比例（0.0 到 1.0）。上方示例裁剪了所有边距的 10%。

输出选项

自定义输出格式和结构：

Markdown 选项

{
  "output_options": {
    "markdown": {
      "annotate_links": true,
      "pages": {
        "prefix": "## Page {pageNumber}\n",
        "custom_page_separator": "\n\n== {pageNumber} ==\n\n",
      },
      "headers_footers": {
        "hide_headers": true,
        "hide_footers": false,
        "page_header_prefix": "Header: ",
        "page_footer_suffix": " (Footer)"
      },
      "tables": {
        "compact_markdown_tables": false,
        "output_tables_as_markdown": false,
        "markdown_table_multiline_separator": " | "
      }
    }
  }
}

空间文本选项

{
  "output_options": {
    "spatial_text": {
      "preserve_layout_alignment_across_pages": true,
      "preserve_very_small_text": false,
      "do_not_unroll_columns": false
    }
  }
}

导出选项

{
  "output_options": {
    "tables_as_spreadsheet": {
      "enable": true,
      "guess_sheet_name": true
    },
    "extract_layout": {
      "enable": true,
      "ignore_document_elements_for_layout_detection": false
    },
    "vectorial_objects": {
      "enable": true
    },
    "embedded_images": {
      "enable": true
    },
    "screenshots": {
      "enable": true
    },
    "export_pdf": {
      "enable": false
    }
  }
}

Webhook 配置

设置作业完成的通知：

{
  "webhook_configurations": [
    {
      "webhook_url": "https://your-app.com/webhook",
      "webhook_headers": {
        "X-Custom-Header": "value"
      },
      "webhook_events": ["parse.done"]
    }
  ]
}

注意: 目前仅使用第一个网络钩子配置。

处理控制

配置超时和错误处理：

{
  "processing_control": {
    "timeouts": {
      "base_in_seconds": 300,
      "extra_time_per_page_in_seconds": 30
    },
    "job_failure_conditions": {
      "allowed_page_failure_ratio": 0.1,
      "fail_on_image_extraction_error": false,
      "fail_on_image_ocr_error": false,
      "fail_on_markdown_reconstruction_error": true,
      "fail_on_buggy_font": false
    },
    "fallback_content": {
      "mode": "empty_page",
      "prefix": "ERROR: ",
      "suffix": " (failed to parse)"
    }
  }
}

缓存控制

禁用缓存以获取最新结果：

{
  "disable_cache": true
}

当 true 时，这将同时使任何现有缓存失效并阻止新结果的缓存。

始终启用的功能

以下功能在 v2 版本中始终启用且无法禁用：

adaptive_long_table: 自适应长表格检测
high_res_ocr: 高分辨率OCR处理
merge_tables_across_pages_in_markdown: 跨页面表格合并
outlined_table_extraction: 表格轮廓提取

这些被设为默认值是因为它们能改善大多数文档的结果。

完整配置示例

文件ID解析示例（推荐）

curl -X POST \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "existing-file-id",
    "parse_options": {
      "parse_mode": "parse_with_llm",
      "parse_with_llm_options": {
        "model": "gpt-4o",
        "prompts": {
          "user_prompt": "Extract all financial data and preserve table structure"
        },
        "ignore": {
          "ignore_diagonal_text": true,
          "ignore_text_in_image": false
        },
        "ocr_parameters": {
          "languages": ["en", "es"]
        }
      }
    },
    "page_ranges": {
      "max_pages": 20,
      "target_pages": "1-5,10,15-20"
    },
    "crop_box": {
      "top": 0.05,
      "bottom": 0.95,
      "left": 0.05,
      "right": 0.95
    },
    "output_options": {
      "markdown": {
        "annotate_links": true,
        "pages": {
          "prefix": "# Page {pageNumber}\n"
        },
        "tables": {
          "output_tables_as_markdown": true
        }
      },
      "extract_layout": {
        "enable": true
      },
      "screenshots": {
        "enable": true
      }
    },
    "webhook_configurations": [
      {
        "webhook_url": "https://myapp.com/webhook",
        "webhook_events": ["parse.done"]
      }
    ],
    "processing_control": {
      "timeouts": {
        "base_in_seconds": 600
      },
      "job_failure_conditions": {
        "allowed_page_failure_ratio": 0.05
      }
    },
    "disable_cache": false
  }' \
  "https://api.cloud.llamaindex.ai/api/v2alpha1/parse"

URL解析示例

curl -X POST \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_url": "https://example.com/report.pdf",
    "http_proxy": "https://proxy.example.com",
    "parse_options": {
      "parse_mode": "parse_with_llm",
      "parse_with_llm_options": {
        "model": "gpt-4o",
        "prompts": {
          "user_prompt": "Extract all financial data and preserve table structure"
        }
      }
    },
    "page_ranges": {
      "max_pages": 20
    },
    "output_options": {
      "extract_layout": {
        "enable": true
      }
    },
    "webhook_configurations": [{
      "webhook_url": "https://myapp.com/webhook",
      "webhook_events": ["parse.done"]
    }]
  }' \
  "https://api.cloud.llamaindex.ai/api/v2alpha1/parse/url"

多部分上传示例

curl -X POST \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" \
  -F "file=@document.pdf" \
  -F 'configuration={
    "parse_options": {
      "parse_mode": "parse_with_llm",
      "parse_with_llm_options": {
        "model": "gpt-4o",
        "prompts": {
          "user_prompt": "Extract all financial data and preserve table structure"
        },
        "ignore": {
          "ignore_diagonal_text": true,
          "ignore_text_in_image": false
        },
        "ocr_parameters": {
          "languages": ["en", "es"]
        }
      }
    },
    "page_ranges": {
      "max_pages": 20,
      "target_pages": "1-5,10,15-20"
    },
    "crop_box": {
      "top": 0.05,
      "bottom": 0.95,
      "left": 0.05,
      "right": 0.95
    },
    "output_options": {
      "markdown": {
        "annotate_links": true,
        "pages": {
          "prefix": "# Page {pageNumber}\n"
        },
        "tables": {
          "output_tables_as_markdown": true
        }
      },
      "extract_layout": {
        "enable": true
      },
      "screenshots": {
        "enable": true
      }
    },
    "webhook_configurations": [
      {
        "webhook_url": "https://myapp.com/webhook",
        "webhook_events": ["parse.done"]
      }
    ],
    "processing_control": {
      "timeouts": {
        "base_in_seconds": 600
      },
      "job_failure_conditions": {
        "allowed_page_failure_ratio": 0.05
      }
    },
    "disable_cache": false
  }' \
  "https://api.cloud.llamaindex.ai/api/v2alpha1/parse/upload"

Base64 上传示例

curl -X POST \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "base64_file": "'$(base64 -w 0 document.pdf)'",
    "filename": "document.pdf",
    "parse_options": {
      "parse_mode": "preset",
      "preset_options": {
        "preset": "scientific"
      }
    }
  }' \
  "https://api.cloud.llamaindex.ai/api/v2alpha1/parse/base64"

文件ID解析示例

curl -X POST \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "existing-file-id",
    "parse_options": {
      "parse_mode": "parse_with_agent",
      "parse_with_agent_options": {}
    },
    "output_options": {
      "extract_layout": {
        "enable": true
      }
    }
  }' \
  "https://api.cloud.llamaindex.ai/api/v2alpha1/parse"

错误处理

v2 提供详细的验证错误信息：

{
  "detail": [
    {
      "type": "value_error",
      "loc": ["parse_options", "parse_with_llm_options"],
      "msg": "parse_with_llm_options can only be used with parse_mode 'parse_with_llm'",
      "input": {...}
    }
  ]
}

响应格式

响应结构保持与v1相同，返回包含任务详情和状态的 ParsingJob 对象。

从 v1 版本迁移

如果您正在从 v1 版本迁移，请参阅我们的详细迁移指南了解参数映射和重大变更。

LlamaParse API v2 指南

快速入门

基本用法

与v1版本的不同之处

端点详情

文件ID解析（推荐）

URL解析

多部分文件上传

Base64 文件上传

选择正确的端点

配置结构

文件ID解析 (/) - 推荐

URL解析 (/url)

多部分上传 (/upload)

Base64上传 (/base64)

解析模式

预设模式 ("preset")

不使用AI解析 ("parse_without_ai")

使用LLM解析 ("parse_with_llm")

使用外部提供商解析 ("parse_with_external_provider")

使用智能体解析 ("parse_with_agent")

使用布局智能体解析 ("parse_with_layout_agent")

自动模式 ("auto")

输入选项

HTML 选项

PDF选项

电子表格选项

演示选项

页面范围

裁剪框

输出选项

Markdown 选项

空间文本选项

导出选项

Webhook 配置

处理控制

缓存控制

始终启用的功能

完整配置示例

文件ID解析示例（推荐）

URL解析示例

多部分上传示例

Base64 上传示例

文件ID解析示例

错误处理

响应格式

从 v1 版本迁移

文件ID解析 (`/`) - 推荐

URL解析 (`/url`)

多部分上传 (`/upload`)

Base64上传 (`/base64`)

预设模式 (`"preset"`)

不使用AI解析 (`"parse_without_ai"`)

使用LLM解析 (`"parse_with_llm"`)

使用外部提供商解析 (`"parse_with_external_provider"`)

使用智能体解析 (`"parse_with_agent"`)

使用布局智能体解析 (`"parse_with_layout_agent"`)

自动模式 (`"auto"`)