# 網頁讀取

以 Markdown、文字、HTML 或截圖格式讀取 URL。

以你的應用程式可消費的格式讀取特定網頁。

所有範例都使用來自[總覽](https://openapi.felo.ai/zh-TW/docs/data-api/guides/felo-overview.md)的 `FELO_API_KEY`。呼叫會使用 **平台餘額**，不是 Felo Pro 點數。回應範例僅供說明；實際內容與可選欄位會有所不同。

## 端點

`POST /api/v1/data/web/read`

## 請求

| 欄位 | 類型 | 必填 | 意義 |
|---|---|---|---|
| `url` | string | 是 | HTTP 或 HTTPS 頁面 URL |
| `formats` | string array | 否 | 只能選擇 `MARKDOWN`、`TEXT`、`HTML`、`SCREENSHOT` 其中之一；預設為 Markdown |
| `mode` | string | 否 | `quality`（預設）、`fast` 或 `auto` |
| `timeout` | integer | 否 | 毫秒逾時，1–60,000；預設 30,000 |
| `totalTimeout` | integer | 否 | 毫秒總逾時，1–60,000；預設為 `timeout` |

每次請求只選擇一種輸出格式；不要在同一個陣列中同時送出全部四種。

```bash
curl -sS --request POST "https://openapi.felo.ai/api/v1/data/web/read" \
  -H "Authorization: Bearer $FELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","formats":["MARKDOWN"],"mode":"quality","timeout":30000}'
```

## 回應

HTTP 200 會在 JSON 根層回傳所選內容欄位。Markdown 回應可能如下：

```json
{
  "title": "Example Domain",
  "markdown": "# Example Domain\n\nThis domain is for use in documentation examples.",
  "metadata": {}
}
```

請依你要求的格式讀取 `markdown`、`text`、`html` 或 `screenshot`。其他中繼資料為選填；不要要求每個格式欄位都必須存在。完整回應請參閱 [OpenAPI 定義](https://openapi.felo.ai/api/v1/data/openapi.json) 中的 `WebReadResponse` schema。

## 計費與失敗

`web.read` 會按請求計費。逾時不等於空白頁面：在使用本文之前，先檢查 HTTP 狀態。逾時後不要改成重複快速請求；請遵循[計費與錯誤](https://openapi.felo.ai/zh-TW/docs/data-api/guides/felo-billing.md)。