> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firecrawl.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Elixir

> Firecrawl Elixir SDK 是 Firecrawl API v2 的自动生成客户端，基于 Req 和 NimbleOptions 构建。

可在你的 Elixir 应用中抓取单个页面、爬取整个站点，并映射 URL。该 SDK 在运行时通过 NimbleOptions 验证所有参数，并使用 Req 进行 HTTP 请求，因此在真正发出请求之前，你就能清楚发现拼写错误和无效选项。

每个函数都有一个 bang (`!`) 变体，出错时会直接抛出异常，而不是返回 `{:error, ...}` 元组。

<div id="installation">
  ## 安装
</div>

在 `mix.exs` 的依赖项列表中添加 `firecrawl`，并配置你的 API 密钥：

```elixir Elixir theme={null}
# 添加到 mix.exs
{:firecrawl, "~> 1.0"}

# 然后在 config.exs 中配置您的 API 密钥
config :firecrawl, api_key: "fc-YOUR-API-KEY"
```

或者在每次请求中传入 API 密钥：

```elixir Elixir theme={null}
Firecrawl.scrape_and_extract_from_url([url: "https://example.com"], api_key: "fc-YOUR-API-KEY")
```

<div id="usage">
  ## 使用方式
</div>

1. 前往 [firecrawl.dev](https://firecrawl.dev) 获取 API 密钥
2. 在应用配置中设置 API 密钥，或将其作为选项传给任意函数。

```elixir Elixir theme={null}
# 抓取网页：
{:ok, scrape_result} = Firecrawl.scrape_and_extract_from_url(
  url: "https://firecrawl.dev",
  formats: ["markdown", "html"]
)
IO.inspect(scrape_result.body)

# 爬取网页：
{:ok, crawl_result} = Firecrawl.crawl_urls(
  url: "https://firecrawl.dev",
  limit: 100,
  scrape_options: [
    formats: ["markdown", "html"]
  ]
)
IO.inspect(crawl_result.body)
```

<div id="scraping-a-url">
  ### 抓取 URL
</div>

使用 `scrape_and_extract_from_url` 抓取单个 URL。它会以结构化数据的形式返回页面内容，包括 markdown、元数据以及你指定的其他 formats。

```elixir Elixir theme={null}
# 抓取网站：
{:ok, result} = Firecrawl.scrape_and_extract_from_url(url: "https://firecrawl.dev", formats: ["markdown", "html"])
IO.inspect(result.body)
```

<div id="crawl-a-website">
  ### 爬取网站
</div>

要爬取网站，请使用 `crawl_urls`。它接收起始 URL 和可选参数，例如页面上限、允许的域名以及输出格式。

```elixir Elixir theme={null}
{:ok, result} = Firecrawl.crawl_urls(url: "https://docs.firecrawl.dev", limit: 5)
IO.inspect(result.body)
```

<div id="start-a-crawl">
  ### 开始爬取
</div>

启动一个爬取任务，并立即返回任务 ID，无需阻塞：

```elixir Elixir theme={null}
{:ok, job} = Firecrawl.crawl_urls(url: "https://docs.firecrawl.dev", limit: 10)
crawl_id = job.body["id"]
IO.puts(crawl_id)
```

<div id="checking-crawl-status">
  ### 查看爬取状态
</div>

使用 `get_crawl_status` 查看爬取任务的状态：

```elixir Elixir theme={null}
{:ok, status} = Firecrawl.get_crawl_status("<crawl-id>")
IO.inspect(status.body)
```

<div id="cancelling-a-crawl">
  ### 取消爬取任务
</div>

使用 `cancel_crawl` 取消爬取任务：

```elixir Elixir theme={null}
{:ok, result} = Firecrawl.cancel_crawl("<crawl-id>")
IO.puts("Cancelled: #{inspect(result.body)}")
```

<div id="map-a-website">
  ### 为网站映射 URL 列表
</div>

使用 `map_urls` 生成网站的 URL 列表：

```elixir Elixir theme={null}
{:ok, result} = Firecrawl.map_urls(url: "https://firecrawl.dev", limit: 10)
IO.inspect(result.body)
```

<div id="search">
  ### 搜索
</div>

进行网页搜索，并可按需抓取结果：

```elixir Elixir theme={null}
{:ok, result} = Firecrawl.search_and_scrape(query: "firecrawl web scraping", limit: 5)
IO.inspect(result.body["data"]["web"])
```

<div id="batch-scrape">
  ### 批量抓取
</div>

在单个批量任务中抓取多个 URL：

```elixir Elixir theme={null}
{:ok, result} = Firecrawl.scrape_and_extract_from_urls(
  urls: ["https://firecrawl.dev", "https://docs.firecrawl.dev"],
  formats: ["markdown"]
)
IO.inspect(result.body)
```

<div id="agent">
  ### 代理
</div>

启动一个代理式数据提取任务：

```elixir Elixir theme={null}
{:ok, job} = Firecrawl.start_agent(
  prompt: "Extract all product names and prices",
  urls: ["https://example.com/products"]
)
job_id = job.body["id"]

# 轮询状态
{:ok, status} = Firecrawl.get_agent_status(job_id)
IO.inspect(status.body)
```

<div id="browser">
  ## 浏览器
</div>

启动云端浏览器会话并远程执行代码。

<div id="create-a-session">
  ### 创建会话
</div>

```elixir Elixir theme={null}
{:ok, session} = Firecrawl.create_browser_session(ttl: 600)
session_id = session.body["id"]
cdp_url = session.body["cdpUrl"]
live_view_url = session.body["liveViewUrl"]
```

<div id="execute-code">
  ### 执行代码
</div>

```elixir Elixir theme={null}
{:ok, result} = Firecrawl.execute_browser_code(session_id,
  code: ~s(await page.goto("https://news.ycombinator.com")\ntitle = await page.title()\nprint(title)),
  language: "python"
)
IO.inspect(result.body)
```

<div id="profiles">
  ### 配置档案
</div>

在不同会话间保存并复用浏览器状态 (cookies、localStorage 等) ：

```elixir Elixir theme={null}
{:ok, session} = Firecrawl.create_browser_session(
  ttl: 600,
  profile: [
    name: "my-profile",
    save_changes: true
  ]
)
```

<div id="list-close-sessions">
  ### 列出并关闭会话
</div>

```elixir Elixir theme={null}
# 列出活跃会话
{:ok, sessions} = Firecrawl.list_browser_sessions(status: "active")
IO.inspect(sessions.body)

# 关闭会话
{:ok, _} = Firecrawl.delete_browser_session(session_id)
```

<div id="self-hosted-instances">
  ## 自托管实例
</div>

要使用自托管的 Firecrawl 实例，请传入 `base_url` 选项：

```elixir Elixir theme={null}
{:ok, result} = Firecrawl.scrape_and_extract_from_url(
  [url: "https://example.com"],
  base_url: "https://your-instance.com/v2"
)
```

<div id="error-handling">
  ## 错误处理
</div>

非 bang 版本的函数会返回 `{:ok, response}` 或 `{:error, exception}`。Bang 版本在出错时会直接抛出异常。NimbleOptions 会在发送请求前验证所有参数，立即捕获拼写错误、缺少必填字段和类型错误。

```elixir Elixir theme={null}
case Firecrawl.scrape_and_extract_from_url(url: "https://example.com") do
  {:ok, response} -> IO.inspect(response.body)
  {:error, error} -> IO.puts("Error: #{Exception.message(error)}")
end

# 或使用 bang 变体在出错时抛出异常：
response = Firecrawl.scrape_and_extract_from_url!(url: "https://example.com")
IO.inspect(response.body)
```

<div id="all-available-functions">
  ## 所有可用函数
</div>

| 函数                             | 描述          |
| ------------------------------ | ----------- |
| `scrape_and_extract_from_url`  | 抓取单个 URL    |
| `scrape_and_extract_from_urls` | 批量抓取多个 URL  |
| `crawl_urls`                   | 爬取网站        |
| `get_crawl_status`             | 检查爬取任务状态    |
| `get_crawl_errors`             | 获取爬取任务错误    |
| `get_active_crawls`            | 列出正在运行的爬取任务 |
| `cancel_crawl`                 | 取消爬取任务      |
| `map_urls`                     | 映射网站中的 URL  |
| `search_and_scrape`            | 搜索并抓取结果     |
| `start_agent`                  | 启动代理提取任务    |
| `get_agent_status`             | 检查代理任务状态    |
| `cancel_agent`                 | 取消代理任务      |
| `create_browser_session`       | 创建浏览器会话     |
| `execute_browser_code`         | 在浏览器会话中执行代码 |
| `list_browser_sessions`        | 列出浏览器会话     |
| `delete_browser_session`       | 删除浏览器会话     |
| `get_batch_scrape_status`      | 检查批量抓取状态    |
| `get_batch_scrape_errors`      | 获取批量抓取错误    |
| `cancel_batch_scrape`          | 取消批量抓取      |
| `get_credit_usage`             | 获取剩余额度      |

上述每个函数都有一个带 bang (`!`) 的变体 (例如 `scrape_and_extract_from_url!`) ，它会直接抛出错误，而不是返回错误元组。

如需完整的 API 文档，请参见 [hexdocs.pm/firecrawl](https://hexdocs.pm/firecrawl)。