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

# Fetch API 快速开始

> 设置 Bright Data Fetch API，并在 5 分钟内使用 cURL、Python 或 Node.js 获取第一个网页的 Markdown、纯文本、HTML 和 JSON-LD。

本教程展示如何使用 Bright Data Fetch API 获取网页，并以 Markdown、纯文本和 HTML 格式返回。

## 前置条件

* 一个 [Bright Data 账户](https://www.bright.cn/?hs_signup=1\&utm_source=docs)
* 已安装 cURL、Python 3.9+ 或 Node.js 18+

<Steps>
  <Step title="获取您的 API 密钥">
    前往 Bright Data 账户的[用户设置页面](https://www.bright.cn/cp/setting/users)并创建一个 API 密钥，或使用已有的密钥。

    如果您还没有账户，请[在 bright.cn 注册](https://www.bright.cn/?hs_signup=1\&utm_source=docs)。新账户每月可获得 5,000 个免费积分，无需信用卡。请参阅[免费套餐](/cn/general/account/billing-and-pricing/free-tier)。

    <Warning>
      您的 API 密钥仅在创建时显示一次。请妥善复制并存储。
    </Warning>
  </Step>

  <Step title="发送请求">
    我们将使用**按 URL 采集**端点，通过同步请求获取 `https://example.com`。将 `YOUR_API_KEY` 替换为您的 API 密钥：

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST \
        "https://api.brightdata.com/datasets/v3/scrape?dataset_id=gd_m6gjtfmeh43we6cqc&format=json" \
        -H "Authorization: Bearer YOUR_API_KEY" \
        -H "Content-Type: application/json" \
        -d '[{"url": "https://example.com"}]'
      ```

      ```python Python theme={null}
      import requests

      response = requests.post(
          "https://api.brightdata.com/datasets/v3/scrape",
          params={"dataset_id": "gd_m6gjtfmeh43we6cqc", "format": "json"},
          headers={
              "Authorization": "Bearer YOUR_API_KEY",
              "Content-Type": "application/json",
          },
          json=[{"url": "https://example.com"}],
      )

      data = response.json()
      if response.status_code == 202:
          print(f"Job running. Snapshot ID: {data['snapshot_id']}")
      else:
          print(data)
      ```

      ```javascript Node.js theme={null}
      const response = await fetch(
        "https://api.brightdata.com/datasets/v3/scrape?dataset_id=gd_m6gjtfmeh43we6cqc&format=json",
        {
          method: "POST",
          headers: {
            "Authorization": "Bearer YOUR_API_KEY",
            "Content-Type": "application/json",
          },
          body: JSON.stringify([
            { url: "https://example.com" }
          ]),
        }
      );

      const data = await response.json();
      if (response.status === 202) {
        console.log(`Job running. Snapshot ID: ${data.snapshot_id}`);
      } else {
        console.log(data);
      }
      ```
    </CodeGroup>

    您应该会看到 `200` 状态码和一个包含一条记录的 JSON 数组。`202` 表示获取需要超过 1 分钟，请参阅下方说明。处理时间取决于目标网站的情况。

    <Note>
      同步请求最多等待 1 分钟。如果 Bright Data Fetch API 需要更长时间，响应将是 HTTP `202` 和 `snapshot_id`，而不是网页数据，采集会以异步方式继续。可通过[异步工作流](/cn/products/scrapers/scrapers-library/async-requests)获取结果，或通过 [webhook 交付](/cn/products/scrapers/scrapers-library/data-delivery)推送给您。
    </Note>
  </Step>

  <Step title="查看响应">
    Bright Data Fetch API 返回一个 JSON 数组，每个 URL 对应一条记录：

    ```json theme={null}
    [
      {
        "markdown": "This domain is for use in documentation examples without needing permission. This is not a service; avoid relying on it for testing and monitoring purposes.",
        "url": "https://example.com/",
        "final_url": "https://example.com/",
        "html2text": "This domain is for use in documentation examples without needing permission. This is not a service; avoid relying on it for\ntesting and monitoring purposes.",
        "page_html": "<!doctype html><html lang=en><head><meta charset=utf-8>...<title>Example Domain</title>...</head><body><p>This domain is for use in documentation examples without needing permission. ...</p></body></html>\n",
        "page_title": "Example Domain",
        "country": null,
        "timestamp": "2026-10-19T18:10:21.213Z",
        "input": {
          "url": "https://example.com"
        }
      }
    ]
    ```

    此处的 `page_html` 值已截断。`markdown` 适合用于 LLM 提示词，`html2text` 适合纯文本，需要完整源代码时使用 `page_html`。请查看[完整响应结构](/cn/api-reference/scrapers/web-content-apis/fetch-api-collect-by-url)。
  </Step>
</Steps>

您已使用 Bright Data Fetch API 成功获取第一个网页。

## 常见问题

### 我可以在一个请求中获取多个 URL 吗？

可以。向输入数组添加更多对象即可，这些 URL 可以属于不同域名。Bright Data 建议每个同步请求不超过 20 个 URL，这是最佳实践，而非硬性限制。对于更大的批处理，请使用[异步 `/trigger` 端点](/cn/products/scrapers/scrapers-library/async-requests)。

```json theme={null}
[
  {"url": "https://example.com"},
  {"url": "https://en.wikipedia.org/wiki/Web_scraping"},
  {"url": "https://www.python.org"}
]
```

### 收到 401 或 403 错误？

请验证您的 API 密钥是否正确且未过期。可在[账户设置](https://www.bright.cn/cp/setting/users)中创建新密钥。有关详细信息，请参阅[身份验证指南](/cn/api-reference/authentication)。

### 请求超时？

同步请求有 1 分钟的超时限制。如果请求超过此限制，API 返回 HTTP `202` 和 `snapshot_id`，并以异步方式完成任务。对于大批量处理，请使用[异步工作流](/cn/products/scrapers/scrapers-library/async-requests)。

### 为什么记录中缺少某个字段？

没有值的字段可能不会出现在记录中。例如，当网页没有 JSON-LD 元数据时，记录中不包含 `ld_json`。请确认该 URL 可公开访问，并且能在浏览器中打开。

## 后续步骤

<CardGroup cols={3}>
  <Card title="端点" icon="bolt" href="/cn/products/scrapers/fetch-api/send-first-request">
    国家定位、字段选择和批量请求。
  </Card>

  <Card title="异步批量请求" icon="layer-group" href="/cn/products/scrapers/scrapers-library/async-requests">
    在单个批处理作业中获取数百个 URL。
  </Card>

  <Card title="设置 Webhooks" icon="webhook" href="/cn/products/scrapers/scrapers-library/data-delivery">
    在获取完成时自动接收结果。
  </Card>
</CardGroup>