我们可以把这些端点分为两大类：核心爬取功能和辅助功能。

核心爬取功能

1. POST /crawl_sync (同步爬取 - 您正在使用的)

  • 用途: 这是最直接、最简单的爬取方式。

  • 工作模式 (同步): 您发送一个包含目标网址的请求，然后您的程序会一直等待，直到服务器完成所有的工作（启动浏览器、加载页面、提取内容），最后服务器将完整的结果一次性返回给您。

  • 好比: 去快餐店点餐。您点单、付钱、在柜台前等待，然后直接拿到您的汉堡。一次搞定。

  • 适用场景: 非常适合测试、快速获取单个页面的结果，或者在您自己的脚本不介意等待几秒到几十秒的情况下使用。

2. POST /crawl 和 GET /task/{task_id} (异步爬取 - 两步法)

这两个端点需要组合使用，提供了一种更高级、更强大的工作模式。

  • 用途: 处理可能耗时很长的爬取任务，避免请求超时。

  • 工作模式 (异步):

    1. 第一步 (POST /crawl): 您先发送一个爬取请求。服务器收到后，不会马上开始爬取，而是立即返回一个任务ID (task_id)，好比给您一个取餐的号牌。

    2. 第二步 (GET /task/{task_id}): 您拿到 task_id 后，可以过一会儿再用这个 ID 去调用 /task/{task_id} 接口，查询任务的进度（例如：排队中、处理中、已完成、失败）。如果任务已完成，这个接口就会返回最终的爬取结果。

  • 好比: 去一家高级餐厅点一道需要精心烹制的菜。您点单后，服务员给您一个订单号，您可以先做点别的事情，隔一段时间再凭订单号询问菜做好了没有。

  • 适用场景: 构建复杂的应用程序，需要同时发起多个爬取任务而不希望程序被卡住；或者当您要爬取的网站非常庞大，预计会花费几分钟甚至更长时间时，使用异步模式可以防止您的请求因为超时而失败。

3. POST /crawl_direct (直接爬取)

  • 用途: 从命名上看，它很可能也是一个同步端点，类似于 /crawl_sync。

  • 推测: “Direct” 可能意味着它绕过了一些高级的内容处理（比如复杂的 Markdown 转换、内容过滤或文章提取），直接返回更“原始”的页面数据（例如，只提取纯文本或基础HTML）。这会让它的处理速度更快，但返回的信息没有经过深度加工。

辅助功能

4. GET /health (健康检查)

  • 用途: 这是一个标准的接口，用于监控服务是否还“活着”。

  • 工作模式: 当您访问这个端点时，如果服务正常，它会返回一个成功的响应（例如 {"status": "ok"}）。自动化监控系统会定期调用这个接口，如果发现调用失败或超时，就会发出警报，提醒管理员服务可能出问题了。

5. GET / (根路径)

  • 用途: API 的“欢迎页面”。

  • 工作模式: 直接访问您 Space 的根地址时，就会调用这个端点，返回一些基本信息，比如欢迎语和文档地址。您之前看到的 {"message":"Welcome to Crawl4AI API",...} 就是它的返回结果。

总结表格

端点 (Endpoint)

HTTP 方法

主要用途

工作模式

/crawl_sync

POST

同步爬取 (推荐)

一次请求，等待，直接返回完整结果。

/crawl

POST

异步爬取 (启动任务)

立即返回 task_id，任务在后台执行。

/task/{task_id}

GET

异步爬取 (获取结果)

使用 task_id 查询任务状态和结果。

/crawl_direct

POST

直接爬取

推测为简化的同步爬取，返回原始数据。

/health

GET

健康检查

供监控系统使用，确认服务是否在线。

/

GET

欢迎页面

显示 API 的基本信息。

对于您目前的测试和大多数直接使用场景，继续使用 /crawl_sync 是最简单、最直观的选择。当您未来需要构建更复杂的应用时，再考虑使用 /crawl 和 /task/{task_id} 的异步模式。