> ## Documentation Index
> Fetch the complete documentation index at: https://firecrawl-noaa-mar-900-create-self-partnership-provisioning.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 解析

上传本地或非公开文档，并将其转换为整洁、可供 LLM 使用的数据。`/parse` 通过 `multipart/form-data` 接收文件二进制内容，并返回 Markdown、JSON、HTML、链接、图像或摘要——同时保留阅读顺序和表格。

* 将 PDF、DOCX、XLSX、HTML 等转换为 Markdown 或结构化 JSON
* 借助基于 Rust 的引擎，解析速度最高可提升 **5 倍**
* 单次请求最多支持 **50 MB** 的文件
* 支持零数据保留

<div id="when-to-use-parse">
  ## 何时使用 `/parse`
</div>

当源文档是**本地文件**或**无法通过公开 URL 访问**时，请使用 `/parse`。如果你有一个指向文档的公开 URL，建议优先使用 [`/scrape`](/zh/api-reference/endpoint/scrape)——它会根据扩展名或内容类型自动识别文件类型，并以相同方式解析。

| 来源                                                | 端点                                                  |
| ------------------------------------------------- | --------------------------------------------------- |
| 指向文档的公开 URL (例如 `https://example.com/report.pdf`) | [`POST /scrape`](/zh/api-reference/endpoint/scrape) |
| 本地文件或非公开字节流 (PDF、DOCX、XLSX、HTML 等)                | `POST /parse` (此端点)                                 |


## OpenAPI

````yaml /zh/api-reference/v2-openapi.json POST /parse
openapi: 3.0.0
info:
  title: Firecrawl API
  version: v2
  description: 用于与 Firecrawl 服务交互，执行网页抓取和爬取任务的 API。
  contact:
    name: Firecrawl Support
    url: https://firecrawl.dev/support
    email: support@firecrawl.dev
servers:
  - url: https://api.firecrawl.dev/v2
security:
  - bearerAuth: []
paths:
  /parse:
    post:
      tags:
        - Scraping
      summary: 上传并解析文件
      operationId: parseFile
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: >-
                    要解析的文件字节。支持的扩展名：.html、.htm、.pdf、.docx、.doc、.odt、.rtf、.xlsx、.xls。
                options:
                  $ref: '#/components/schemas/ParseOptions'
              required:
                - file
            encoding:
              options:
                contentType: application/json
      responses:
        '200':
          description: 成功响应
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScrapeResponse'
        '400':
          description: 错误请求
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  code:
                    type: string
                    example: BAD_REQUEST
                  error:
                    type: string
                    example: Invalid multipart form-data request.
        '402':
          description: 需要支付
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Payment required to access this resource.
        '429':
          description: 请求过多
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: >-
                      Request rate limit exceeded. Please wait and try again
                      later.
        '500':
          description: 服务器错误
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  code:
                    type: string
                    example: UNKNOWN_ERROR
                  error:
                    type: string
                    example: An unexpected error occurred on the server.
      security:
        - bearerAuth: []
components:
  schemas:
    ParseOptions:
      type: object
      description: 可选的解析选项，以 JSON 形式通过 multipart 的 `options` 字段传递。
      properties:
        formats:
          $ref: '#/components/schemas/ParseFormats'
        onlyMainContent:
          type: boolean
          description: 仅返回页面的主要内容，不包括页眉、导航栏、页脚等。
          default: true
        includeTags:
          type: array
          items:
            type: string
          description: 要包含在输出中的标签。
        excludeTags:
          type: array
          items:
            type: string
          description: 要从输出中排除的标签。
        headers:
          type: object
          description: 在需要发起额外网络请求时发送的请求头。
        timeout:
          type: integer
          description: 请求超时时间（毫秒）。默认值为 30000（30 秒）。最大值为 300000（300 秒）。
          default: 30000
          maximum: 300000
        parsers:
          type: array
          description: 在适用时控制文件解析器的行为（例如 PDF 解析器模式）。
          items:
            oneOf:
              - type: object
                properties:
                  type:
                    type: string
                    enum:
                      - pdf
                  mode:
                    type: string
                    enum:
                      - fast
                      - auto
                      - ocr
                    default: auto
                    description: >-
                      PDF 解析模式。`fast`：仅提取文本。`auto`：优先提取文本，失败时回退到
                      OCR。`ocr`：对每一页执行 OCR。
                  maxPages:
                    type: integer
                    minimum: 1
                    maximum: 10000
                    description: 从 PDF 中最多解析的页数。
                required:
                  - type
                additionalProperties: false
          default:
            - pdf
        skipTlsVerification:
          type: boolean
          description: 发起请求时跳过 TLS 证书验证。
          default: true
        removeBase64Images:
          type: boolean
          description: 从输出中移除 base64 编码的图片，并保留 alt 文本占位符。
          default: true
        blockAds:
          type: boolean
          description: 启用广告和 Cookie 弹窗拦截。
          default: true
        proxy:
          type: string
          enum:
            - basic
            - auto
          description: 解析上传使用的代理模式。`/parse` 仅支持 `basic` 和 `auto`。
        origin:
          type: string
          description: 用于分析和日志记录的 origin 标识符。
          default: api
        integration:
          type: string
          nullable: true
          description: 可选的 integration 标识符。
        zeroDataRetention:
          type: boolean
          default: false
          description: 如果为 true，将为此次解析启用 zero data retention。要启用此功能，请联系 help@firecrawl.dev。
    ScrapeResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
          properties:
            markdown:
              type: string
            summary:
              type: string
              nullable: true
              description: 如果 `formats` 中包含 `summary`，则返回页面摘要
            html:
              type: string
              nullable: true
              description: >-
                如果 `formats` 中包含 `html`，则返回页面清洗后的 HTML 内容。会移除
                `<script>`、`<style>`、`<noscript>`、`<meta>` 和 `<head>` 标签；将相对 URL
                转换为绝对 URL；将响应式图片的 `srcset` 解析为分辨率最高的版本。遵循
                `onlyMainContent`、`includeTags` 和 `excludeTags` 过滤器。
            rawHtml:
              type: string
              nullable: true
              description: >-
                如果在 `formats` 中指定 `rawHtml`，则会返回页面的原始
                HTML（未作任何修改）。不会执行任何清理或过滤操作。
            screenshot:
              type: string
              nullable: true
              description: 如果在 `formats` 中包含 `screenshot`，则会返回页面截图。截图将在 24 小时后过期，届时将无法再下载。
            audio:
              type: string
              nullable: true
              description: >-
                如果 `formats` 中包含 `audio`，则返回提取后的 MP3 音频文件的签名 URL。该签名 URL 会在 1
                小时后过期。
            video:
              type: string
              nullable: true
              description: 如果 `formats` 中包含 `video`，则返回提取后视频文件的签名 URL。该签名 URL 会在 1 小时后过期。
            answer:
              type: string
              nullable: true
              description: >-
                通过 `question` 格式提供的问题的自然语言答案。仅当 `formats` 中包含 `question`
                格式对象时才会出现。
            highlights:
              type: string
              nullable: true
              description: >-
                由 `highlights` 格式选取的相关源文本。仅当 `formats` 中包含 `highlights`
                格式对象时才会出现。
            links:
              type: array
              items:
                type: string
              description: 当 `formats` 中包含 `links` 时，页面上的链接列表
            actions:
              type: object
              nullable: true
              description: '`actions` 参数中指定的 actions 的执行结果。仅当请求中提供了 `actions` 参数时才会返回。'
              properties:
                screenshots:
                  type: array
                  description: 截图 URL，顺序与提供的 screenshot actions 保持一致。
                  items:
                    type: string
                    format: url
                scrapes:
                  type: array
                  description: 按照所提供的 scrape actions 顺序抓取内容。
                  items:
                    type: object
                    properties:
                      url:
                        type: string
                      html:
                        type: string
                javascriptReturns:
                  type: array
                  description: 与所提供的 executeJavascript actions 顺序一致的 JavaScript 返回值。
                  items:
                    type: object
                    properties:
                      type:
                        type: string
                      value: {}
                pdfs:
                  type: array
                  description: 按提供的 pdf actions 的顺序生成的 PDF。
                  items:
                    type: string
            metadata:
              type: object
              properties:
                title:
                  oneOf:
                    - type: string
                    - type: array
                      items:
                        type: string
                  description: 从页面提取的标题，可以是一个字符串或字符串数组
                description:
                  oneOf:
                    - type: string
                    - type: array
                      items:
                        type: string
                  description: 从页面提取的描述，可以是字符串或字符串数组。
                language:
                  oneOf:
                    - type: string
                    - type: array
                      items:
                        type: string
                  nullable: true
                  description: 从页面提取的语言，可以是字符串或字符串数组
                sourceURL:
                  type: string
                  format: uri
                  description: 发起请求时使用的原始 URL。如果发生重定向，可能与最终页面的 URL 不一致。
                url:
                  type: string
                  format: uri
                  description: 跟随所有重定向后得到的最终页面 URL。
                keywords:
                  oneOf:
                    - type: string
                    - type: array
                      items:
                        type: string
                  description: 从页面中提取的关键词，可以是字符串或字符串数组
                ogLocaleAlternate:
                  type: array
                  items:
                    type: string
                  description: 页面的其他可用语言版本
                '<any other metadata> ':
                  oneOf:
                    - type: string
                    - type: array
                      items:
                        type: string
                  description: 从 HTML 提取的其他元数据，可以是字符串或字符串数组
                statusCode:
                  type: integer
                  description: 页面状态码
                contentType:
                  type: string
                  description: 页面的内容类型（MIME 类型），如 text/html、application/pdf
                error:
                  type: string
                  nullable: true
                  description: 页面错误信息
                concurrencyLimited:
                  type: boolean
                  description: 此次抓取是否因团队并发限制而被限流
                concurrencyQueueDurationMs:
                  type: number
                  description: 该请求在并发队列中的等待时间（毫秒）。仅当 concurrencyLimited 为 true 时返回。
            warning:
              type: string
              nullable: true
              description: 在使用 LLM Extraction 时会显示。警告信息会提示你提取过程中的任何问题。
            changeTracking:
              type: object
              nullable: true
              description: >-
                当 `formats` 中包含 `changeTracking` 时的变更追踪信息。仅在请求 `changeTracking`
                格式时才会返回。
              properties:
                previousScrapeAt:
                  type: string
                  format: date-time
                  nullable: true
                  description: 当前页面用于对比的上一次抓取时间戳。如果不存在之前的抓取，则为 null。
                changeStatus:
                  type: string
                  enum:
                    - new
                    - same
                    - changed
                    - removed
                  description: >-
                    两个页面版本之间的比较结果。`new` 表示该页面之前不存在，`same` 表示内容没有变化，`changed`
                    表示内容已发生变化，`removed` 表示该页面已被移除。
                visibility:
                  type: string
                  enum:
                    - visible
                    - hidden
                  description: >-
                    当前页面/URL 的可见性。`visible` 表示该 URL 是通过自然途径（链接或站点地图）发现的，`hidden`
                    表示该 URL 是通过之前抓取的历史记录（“记忆”）发现的。
                diff:
                  type: string
                  nullable: true
                  description: 在使用“git-diff”模式时的 Git 风格变更 diff。仅在模式设置为“git-diff”时返回。
                json:
                  type: object
                  nullable: true
                  description: >-
                    使用 `json` 模式时的 JSON 比较结果。仅在模式设置为 `json` 时返回。该字段会根据 `schema`
                    中定义的类型，输出一个列表，包含 `previous` 和 `current` 抓取结果中的所有键及其对应的值。示例见
                    [此处](/features/change-tracking)
            branding:
              type: object
              nullable: true
              description: 如果在 `formats` 中包含 `branding`，则会从页面中提取品牌相关信息，包括颜色、字体、版式、间距、组件等。
              properties:
                colorScheme:
                  type: string
                  enum:
                    - light
                    - dark
                  description: 页面检测到的配色方案。
                logo:
                  type: string
                  nullable: true
                  description: 主徽标的 URL。
                colors:
                  type: object
                  nullable: true
                  description: 从页面中提取的品牌颜色。
                  properties:
                    primary:
                      type: string
                      description: 主品牌颜色（十六进制颜色值）。
                    secondary:
                      type: string
                      description: 次要品牌颜色（十六进制颜色值）。
                    accent:
                      type: string
                      description: 强调色（十六进制颜色值）。
                    background:
                      type: string
                      description: 背景颜色（十六进制颜色值）。
                    textPrimary:
                      type: string
                      description: 主文本颜色（十六进制颜色值）。
                    textSecondary:
                      type: string
                      description: 次要文本颜色（十六进制颜色值）。
                    link:
                      type: string
                      description: 链接颜色（十六进制颜色值）。
                    success:
                      type: string
                      description: 成功 / 正向状态颜色（十六进制）。
                    warning:
                      type: string
                      description: 警告状态颜色（十六进制）。
                    error:
                      type: string
                      description: 错误 / 危险状态颜色（十六进制）。
                fonts:
                  type: array
                  nullable: true
                  description: 页面中使用的字体族数组。
                  items:
                    type: object
                    properties:
                      family:
                        type: string
                        description: 字体族名称。
                typography:
                  type: object
                  nullable: true
                  description: 详细的排版配置。
                  properties:
                    fontFamilies:
                      type: object
                      description: 按角色划分的字体族配置。
                      properties:
                        primary:
                          type: string
                          description: 主字体族。
                        heading:
                          type: string
                          description: 标题字体族。
                        code:
                          type: string
                          description: 代码 / 等宽字体族。
                    fontSizes:
                      type: object
                      description: 各文本层级的字体大小。
                      properties:
                        h1:
                          type: string
                        h2:
                          type: string
                        h3:
                          type: string
                        body:
                          type: string
                    fontWeights:
                      type: object
                      description: 字重（font weight）规范。
                      properties:
                        light:
                          type: integer
                        regular:
                          type: integer
                        medium:
                          type: integer
                        bold:
                          type: integer
                    lineHeights:
                      type: object
                      description: 各类文本的行高（line-height）。
                      properties:
                        heading:
                          type: string
                        body:
                          type: string
                spacing:
                  type: object
                  nullable: true
                  description: 间距与布局相关信息。
                  properties:
                    baseUnit:
                      type: integer
                      description: 基准间距（像素）。
                    borderRadius:
                      type: string
                      description: 默认圆角半径。
                    padding:
                      type: object
                      description: 内边距（padding）规格。
                    margins:
                      type: object
                      description: 外边距（margin）规格。
                components:
                  type: object
                  nullable: true
                  description: UI 组件样式规范。
                  properties:
                    buttonPrimary:
                      type: object
                      description: 主按钮样式规范。
                      properties:
                        background:
                          type: string
                        textColor:
                          type: string
                        borderRadius:
                          type: string
                    buttonSecondary:
                      type: object
                      description: 次级按钮样式配置。
                      properties:
                        background:
                          type: string
                        textColor:
                          type: string
                        borderColor:
                          type: string
                        borderRadius:
                          type: string
                    input:
                      type: object
                      description: 输入框样式配置。
                icons:
                  type: object
                  nullable: true
                  description: 图标样式配置。
                images:
                  type: object
                  nullable: true
                  description: 品牌相关图片。
                  properties:
                    logo:
                      type: string
                      description: Logo 图片 URL。
                    favicon:
                      type: string
                      description: 网站图标（favicon）URL。
                    ogImage:
                      type: string
                      description: Open Graph 图片 URL。
                animations:
                  type: object
                  nullable: true
                  description: 动效与过渡配置。
                layout:
                  type: object
                  nullable: true
                  description: 布局配置（栅格、页眉/页脚高度）。
                personality:
                  type: object
                  nullable: true
                  description: 品牌个性特征（语气、活力、目标受众）。
    ParseFormats:
      type: array
      items:
        oneOf:
          - type: object
            title: Markdown
            properties:
              type:
                type: string
                enum:
                  - markdown
            required:
              - type
          - type: object
            title: Summary
            properties:
              type:
                type: string
                enum:
                  - summary
            required:
              - type
          - type: object
            title: HTML
            properties:
              type:
                type: string
                enum:
                  - html
            required:
              - type
          - type: object
            title: Raw HTML
            properties:
              type:
                type: string
                enum:
                  - rawHtml
            required:
              - type
          - type: object
            title: Links
            properties:
              type:
                type: string
                enum:
                  - links
            required:
              - type
          - type: object
            title: Images
            properties:
              type:
                type: string
                enum:
                  - images
            required:
              - type
          - type: object
            title: JSON
            properties:
              type:
                type: string
                enum:
                  - json
              schema:
                type: object
                description: >-
                  用于 JSON 输出的 schema。必须符合 [JSON
                  Schema](https://json-schema.org/)。
              prompt:
                type: string
                description: 用于 JSON 输出的 prompt。
            required:
              - type
      description: 解析上传支持的输出格式。不支持浏览器渲染格式和变更追踪。
      default:
        - markdown
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````