高级工具文档2 credits

process_document

只需给出文档 URL，即可拿到结构化 JSON。PDF 会返回文本、内嵌元数据、页数和带线表格；CSV 以行的形式返回；纯文本与 HTML 返回其文本内容。文件类型会根据响应头、URL 以及文件自身的魔数自动判定，你无需事先知道。

使用场景

报告摄取

把季度 PDF 转成可比对、可索引、可入数仓的文本与表格。

面向文档的 RAG

提取论文与手册的正文用于切块，标题与作者已单独拆出。

表格采集

把 PDF 中的带线表格提取为行数组，并标明每张表来自哪一页。

文件公告监控

监控监管机构发布的 PDF，一旦有新文件立即解析。

CSV 端点

读取发布在某个 URL 上的 CSV，同时得到原始文本和解析后的行，无需自己下载。

元数据审计

在一批文档中收集内嵌的标题、作者、生成器与日期，找出过时或标注错误的文件。

Endpoint

POST/api/v1/tools/process_document

Auth Required

Free 计划 1 req/s

2 credits

Parameters

Name	Type	Required	Default	Description
url	string	Required	-	要获取的文档。必须是有效的绝对 http 或 https URL。 Example: https://example.com/reports/q3-infrastructure.pdf
document_type	string	Optional	auto	`auto`、`pdf`、`csv`、`txt`、`docx` 或 `xlsx`。`auto` 会根据 `Content-Type` 响应头、URL 扩展名和文件魔数判断。`docx` 与 `xlsx` 能通过校验，但在该端点会返回 501。 Example: auto
extract_text	boolean	Optional	true	以 `text` 返回文档文本，并附 `text_length`。上限为 200,000 个字符；PDF 另限前 200 页——任一限制触发时都会在 `notes` 中说明。 Example: true
extract_metadata	boolean	Optional	true	返回文档的内嵌属性。PDF 提供标题、作者、主题、创建程序、生成器以及两个日期；HTML 提供标题、描述和作者；CSV 与 TXT 不含任何元数据。 Example: true
extract_tables	boolean	Optional	false	以行数组返回带线表格。PDF 最多返回 20 张表、每张最多 1,000 行；CSV 作为单张表返回；HTML 页面会收到一条说明，指出此处不提取表格。 Example: true
extract_images	boolean	Optional	false	托管 REST API 不支持该功能。设置后会返回 `images: null` 并附一条指向 CrawlForge MCP 服务器的说明，而不是假装没找到图片。 Example: false
timeout	number	Optional	30000	抓取超时（毫秒），取值 1000-60000。该端点运行在 30 秒的函数中，因此无论传什么值，抓取都被限制在 20,000 毫秒以内。 Example: 30000
respect_robots	boolean	Optional	true	遵守目标站点的 robots.txt。保持 `true` 时，robots.txt 对 `CrawlForge` 禁止的路径会在抓取之前以 403 拒绝，且不扣除 credits。仅在你与目标站点另有约定时才设为 `false`——此时响应会带上一条 `warnings`，并且该覆盖会记录到你的 API key 上。 Example: true

值得了解的限制

以下每一项都会在 notes 中明确说明，而不是悄悄失败。

每个文档 25MB

先按 Content-Length 检查，再按实际接收到的字节数检查，因此谎报的响应头也无法蒙混过关。

文本取前 200 页

文本与表格只从前 200 页读取。page_count 仍然报告文档的真实页数。

200,000 个字符

超出部分会在该处被截断，并附一条说明。

竖线决定列

只有横线的表格——学术论文的惯例——会保留行，但列数报告为 1，并在 notes 中说明。

请求示例

terminalBash

curl -X POST https://crawlforge.dev/api/v1/tools/process_document \
  -H "X-API-Key: cf_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/reports/q3-infrastructure.pdf",
    "extract_tables": true
  }'

响应示例

200 OK4,210ms

{
  "success": true,
  "data": {
    "url": "https://example.com/reports/q3-infrastructure.pdf",
    "document_type": "pdf",
    "content_type": "application/pdf",
    "file_size": 1842665,
    "processed_at": "2026-08-27T02:27:50.833Z",
    "page_count": 14,
    "text": "Q3 Infrastructure Review\n\nRequest volume grew 38% quarter over quarter while p95 latency held flat...",
    "text_length": 101,
    "metadata": {
      "title": "Q3 Infrastructure Review",
      "author": "Dana Reyes",
      "subject": "Quarterly capacity planning",
      "creator": "LaTeX with hyperref",
      "producer": "pdfTeX-1.40.25",
      "creation_date": "D:20260812141055Z",
      "modification_date": "D:20260814093012Z"
    },
    "tables": [
      {
        "page": 4,
        "rows": 3,
        "columns": 3,
        "data": [
          [
            "Region",
            "Requests",
            "p95 ms"
          ],
          [
            "us-east",
            "18,204,551",
            "412"
          ],
          [
            "eu-west",
            "9,118,340",
            "458"
          ]
        ]
      }
    ]
  },
  "credits_used": 2,
  "credits_remaining": 998,
  "processing_time": 4210
}

Field Descriptions

data.document_type类型检测最终判定的结果，可能与你请求的不同

data.content_type服务器发送的 `Content-Type` 响应头，原样返回——它经常是错的，所以还会检查魔数

data.file_size实际接收到的字节数

data.page_count文档的页数。仅 PDF 有该字段；即使只读取了前 200 页，也会报告完整页数

data.text_length截断之后 `text` 中的字符数，而不是文档的完整长度

data.metadata.creation_datePDF 日期字符串按内嵌原样返回，格式为 `D:YYYYMMDDHHmmSS`。需要你自行解析

data.tables[].page该表格所在的页码，便于把结果追溯回原文

data.tables[].columns由 PDF 中绘制的竖线推导得出。值为 1 表示该表格没有用竖线划分列

credits_used每个文档固定 2 credits，与页数无关

错误处理

URL 无效（400 Bad Request）

VALIDATION_ERROR。url 为必填且必须能解析为绝对 URL。timeout 超出 1000-60000、document_type 取值未知，或 URL 解析到私有/本地地址，也返回同一状态码。

docx 或 xlsx（501 Not Implemented）

UNSUPPORTED_DOCUMENT_TYPE。托管 REST API 不解析 Office 格式。CrawlForge MCP 服务器（npm：crawlforge-mcp-server）可用同一个 API key 处理它们。

文档过大（413 Payload Too Large）

DOCUMENT_TOO_LARGE。超过 25MB 上限。下载前后各检查一次，因此不准确的 Content-Length 同样会被拦下。

无法获取文档（502 Bad Gateway）

URL 返回非 2xx 状态时为 DOCUMENT_FETCH_ERROR（消息中会带上该状态码）；连接本身失败时为 FETCH_FAILED。

目标站点超时（504 Gateway Timeout）

FETCH_TIMEOUT。文档未在抓取时间预算内送达。

处理失败（500 Internal Server Error）

TOOL_ERROR。损坏或加密的 PDF 会落到这里。失败的调用不计费。

被 robots.txt 拦截（403 Forbidden）

目标站点的 robots.txt 对 CrawlForge 禁止了该路径。若你与目标站点另有约定，可设置 respect_robots: false 予以覆盖——该覆盖会记录到你的 API key 上。该覆盖不适用于列入 CrawlForge 永久排除名单的主机——无论 respect_robots 取何值，这类主机一律被拒绝。

注意： 扫描件 PDF 本质上是文字的图片，因此能成功解析但几乎没有内容——page_count 看起来正常，而 text_length 接近于零。该端点不做 OCR；在信任结果之前请先检查 text_length。

credits 费用

2 credits

每个文档 2 credits

统一价格：200 页的 PDF 与 1 页的价格相同，启用表格或元数据也不额外收费。失败的调用不计费。

包含内容：

根据响应头、URL 与魔数进行类型检测

PDF 文本，最多 200 页、200,000 个字符

内嵌的 PDF 元数据，含两个时间戳

最多 20 张带线表格，并附页码

CSV 解析，以及纯文本与 HTML 提取

计划推荐：

Free 计划： 1,000 个一次性试用 credits = 500 个文档

Hobby 计划： 5,000 credits = 2,500 个文档（$19/mo）

Professional 计划： 50,000 credits = 25,000 个文档（$99/mo）

相关工具

extract_content

面向 HTML 文章而不是文档（2 credits）

search_web

用 file_type 过滤器找到要处理的 PDF（5 credits）

summarize_content

随后对提取出的文本做摘要（4 credits）

batch_scrape

一次收集多个 URL，仅支持 HTML（每个 URL 5 credits）

准备好试用 process_document 了吗？免费注册并获得 1,000 credits 开始构建。

使用场景

报告摄取

把季度 PDF 转成可比对、可索引、可入数仓的文本与表格。

面向文档的 RAG

提取论文与手册的正文用于切块，标题与作者已单独拆出。

表格采集

把 PDF 中的带线表格提取为行数组，并标明每张表来自哪一页。

文件公告监控

监控监管机构发布的 PDF，一旦有新文件立即解析。

CSV 端点

读取发布在某个 URL 上的 CSV，同时得到原始文本和解析后的行，无需自己下载。

元数据审计

在一批文档中收集内嵌的标题、作者、生成器与日期，找出过时或标注错误的文件。

Parameters

Name	Type	Required	Default	Description
url	string	Required	-	要获取的文档。必须是有效的绝对 http 或 https URL。 Example: https://example.com/reports/q3-infrastructure.pdf
document_type	string	Optional	auto	`auto`、`pdf`、`csv`、`txt`、`docx` 或 `xlsx`。`auto` 会根据 `Content-Type` 响应头、URL 扩展名和文件魔数判断。`docx` 与 `xlsx` 能通过校验，但在该端点会返回 501。 Example: auto
extract_text	boolean	Optional	true	以 `text` 返回文档文本，并附 `text_length`。上限为 200,000 个字符；PDF 另限前 200 页——任一限制触发时都会在 `notes` 中说明。 Example: true
extract_metadata	boolean	Optional	true	返回文档的内嵌属性。PDF 提供标题、作者、主题、创建程序、生成器以及两个日期；HTML 提供标题、描述和作者；CSV 与 TXT 不含任何元数据。 Example: true
extract_tables	boolean	Optional	false	以行数组返回带线表格。PDF 最多返回 20 张表、每张最多 1,000 行；CSV 作为单张表返回；HTML 页面会收到一条说明，指出此处不提取表格。 Example: true
extract_images	boolean	Optional	false	托管 REST API 不支持该功能。设置后会返回 `images: null` 并附一条指向 CrawlForge MCP 服务器的说明，而不是假装没找到图片。 Example: false
timeout	number	Optional	30000	抓取超时（毫秒），取值 1000-60000。该端点运行在 30 秒的函数中，因此无论传什么值，抓取都被限制在 20,000 毫秒以内。 Example: 30000
respect_robots	boolean	Optional	true	遵守目标站点的 robots.txt。保持 `true` 时，robots.txt 对 `CrawlForge` 禁止的路径会在抓取之前以 403 拒绝，且不扣除 credits。仅在你与目标站点另有约定时才设为 `false`——此时响应会带上一条 `warnings`，并且该覆盖会记录到你的 API key 上。 Example: true

值得了解的限制

以下每一项都会在 notes 中明确说明，而不是悄悄失败。

每个文档 25MB

先按 Content-Length 检查，再按实际接收到的字节数检查，因此谎报的响应头也无法蒙混过关。

文本取前 200 页

文本与表格只从前 200 页读取。page_count 仍然报告文档的真实页数。

200,000 个字符

超出部分会在该处被截断，并附一条说明。

竖线决定列

只有横线的表格——学术论文的惯例——会保留行，但列数报告为 1，并在 notes 中说明。

curl -X POST https://crawlforge.dev/api/v1/tools/process_document \ -H "X-API-Key: cf_test_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com/reports/q3-infrastructure.pdf", "extract_tables": true }'

响应示例

200 OK4,210ms

{
  "success": true,
  "data": {
    "url": "https://example.com/reports/q3-infrastructure.pdf",
    "document_type": "pdf",
    "content_type": "application/pdf",
    "file_size": 1842665,
    "processed_at": "2026-08-27T02:27:50.833Z",
    "page_count": 14,
    "text": "Q3 Infrastructure Review\n\nRequest volume grew 38% quarter over quarter while p95 latency held flat...",
    "text_length": 101,
    "metadata": {
      "title": "Q3 Infrastructure Review",
      "author": "Dana Reyes",
      "subject": "Quarterly capacity planning",
      "creator": "LaTeX with hyperref",
      "producer": "pdfTeX-1.40.25",
      "creation_date": "D:20260812141055Z",
      "modification_date": "D:20260814093012Z"
    },
    "tables": [
      {
        "page": 4,
        "rows": 3,
        "columns": 3,
        "data": [
          [
            "Region",
            "Requests",
            "p95 ms"
          ],
          [
            "us-east",
            "18,204,551",
            "412"
          ],
          [
            "eu-west",
            "9,118,340",
            "458"
          ]
        ]
      }
    ]
  },
  "credits_used": 2,
  "credits_remaining": 998,
  "processing_time": 4210
}

Field Descriptions

data.document_type类型检测最终判定的结果，可能与你请求的不同

data.content_type服务器发送的 `Content-Type` 响应头，原样返回——它经常是错的，所以还会检查魔数

data.file_size实际接收到的字节数

data.page_count文档的页数。仅 PDF 有该字段；即使只读取了前 200 页，也会报告完整页数

data.text_length截断之后 `text` 中的字符数，而不是文档的完整长度

data.metadata.creation_datePDF 日期字符串按内嵌原样返回，格式为 `D:YYYYMMDDHHmmSS`。需要你自行解析

data.tables[].page该表格所在的页码，便于把结果追溯回原文

data.tables[].columns由 PDF 中绘制的竖线推导得出。值为 1 表示该表格没有用竖线划分列

credits_used每个文档固定 2 credits，与页数无关

错误处理

URL 无效（400 Bad Request）

VALIDATION_ERROR。url 为必填且必须能解析为绝对 URL。timeout 超出 1000-60000、document_type 取值未知，或 URL 解析到私有/本地地址，也返回同一状态码。

docx 或 xlsx（501 Not Implemented）

UNSUPPORTED_DOCUMENT_TYPE。托管 REST API 不解析 Office 格式。CrawlForge MCP 服务器（npm：crawlforge-mcp-server）可用同一个 API key 处理它们。

文档过大（413 Payload Too Large）

DOCUMENT_TOO_LARGE。超过 25MB 上限。下载前后各检查一次，因此不准确的 Content-Length 同样会被拦下。

无法获取文档（502 Bad Gateway）

URL 返回非 2xx 状态时为 DOCUMENT_FETCH_ERROR（消息中会带上该状态码）；连接本身失败时为 FETCH_FAILED。

目标站点超时（504 Gateway Timeout）

FETCH_TIMEOUT。文档未在抓取时间预算内送达。

处理失败（500 Internal Server Error）

TOOL_ERROR。损坏或加密的 PDF 会落到这里。失败的调用不计费。

被 robots.txt 拦截（403 Forbidden）

credits 费用

2 credits

每个文档 2 credits

统一价格：200 页的 PDF 与 1 页的价格相同，启用表格或元数据也不额外收费。失败的调用不计费。

包含内容：

根据响应头、URL 与魔数进行类型检测

PDF 文本，最多 200 页、200,000 个字符

内嵌的 PDF 元数据，含两个时间戳

最多 20 张带线表格，并附页码

CSV 解析，以及纯文本与 HTML 提取

计划推荐：

Free 计划： 1,000 个一次性试用 credits = 500 个文档

Hobby 计划： 5,000 credits = 2,500 个文档（$19/mo）

Professional 计划： 50,000 credits = 25,000 个文档（$99/mo）