# Felo 网页读取

POST /api/v1/data/web/read

读取指定网页，并输出应用需要的内容格式。

示例使用[总览](https://openapi.felo.ai/zh-CN/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[] | 否 | 只选一种：`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`。

## 计费与失败处理

`web.read` 按请求计费。超时不代表网页正文为空：先检查 HTTP 状态，再处理内容。超时后不要立即密集重复请求，处理规则见[计费与错误处理](https://openapi.felo.ai/zh-CN/docs/data-api/guides/felo-billing.md)。