# Felo 接口接入说明

Data API 中由 Felo 提供的网页搜索、读取、X 数据、联网问答与 PPT 接口，使用平台余额调用。

Felo 是 [Data API](https://openapi.felo.ai/zh-CN/docs/data-api) 中的供应商之一，提供网页搜索、网页读取、X 数据、联网问答和 PPT 接口。你可以在 Data API 对应的原有分类中找到它们，与其他供应商的接口并列。

这些接口使用**平台余额**，路径以 `/api/v1/data` 开头。本页集中说明认证、首次调用与计费入口。

如果要使用已有的 Felo Pro 积分，请查看[原 Felo APIs](https://openapi.felo.ai/zh-CN/docs/api-reference/felo-apis.md)。平台余额与 Pro 积分分开，不能相互抵扣。

## 完成第一次调用

1. 在[控制台 → API Keys](https://openapi.felo.ai/console/api-keys)创建密钥。
2. 在[控制台 → Billing](https://openapi.felo.ai/console/billing)检查或充值**平台余额**。
3. 在服务器或本地终端设置环境变量：

```bash
export FELO_API_KEY="YOUR_API_KEY"
```

请求携带 `Authorization: Bearer $FELO_API_KEY`。也支持 `X-API-Key`，选择一种认证方式即可。发送 JSON 时还需要 `Content-Type: application/json`。

```bash
curl -sS --request POST "https://openapi.felo.ai/api/v1/data/web/search" \
  -H "Authorization: Bearer $FELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"什么是检索增强生成？","count":3}'
```

HTTP 200 返回 `resources` 数组，包含网页标题、链接和摘要，以及 `total`。需要直接生成带来源的回答时，请使用[联网问答](https://openapi.felo.ai/zh-CN/docs/data-api/guides/felo-chat.md)。

## 按功能阅读

| 文档 | 包含的操作 | 能获得什么 | 计费单位 |
|---|---|---|---|
| [网页搜索](https://openapi.felo.ai/zh-CN/docs/data-api/guides/felo-web-search.md) | 搜索网页 | 标题、链接和摘要 | 请求 |
| [网页读取](https://openapi.felo.ai/zh-CN/docs/data-api/guides/felo-web-read.md) | 读取指定 URL | Markdown、文本、HTML 或截图 | 请求 |
| [X 数据](https://openapi.felo.ai/zh-CN/docs/data-api/guides/felo-x-data.md) | 用户资料、用户搜索、用户帖子、帖子搜索、帖子回复 | 结构化用户与帖子；部分接口支持分页 | 返回结果条数 |
| [联网问答](https://openapi.felo.ai/zh-CN/docs/data-api/guides/felo-chat.md) | 生成回答 | 回答正文与网页来源 | 请求 |
| [PPT 生成与导出](https://openapi.felo.ai/zh-CN/docs/data-api/guides/felo-ppt.md) | 创建、状态、结果、导出、导出状态、删除 | 生成任务与可下载的 PPTX | 生成按页；导出单独计费 |
| [计费与错误处理](https://openapi.felo.ai/zh-CN/docs/data-api/guides/felo-billing.md) | 公共接入说明 | 价格、余额处理与重试规则 | — |

以上覆盖 **14 个核心操作**。如果 PPT 创建响应返回 `stream_key`，还可以按 [PPT 指南](https://openapi.felo.ai/zh-CN/docs/data-api/guides/felo-ppt.md#使用-sse-读取生成过程)读取生成过程的 SSE 事件。查询生成状态、生成结果、导出状态及删除 PPT 不新增费用。

## 从原接口迁移时注意什么

请按实际调用的接口阅读文档，不能只把 `/v2` 替换为 `/api/v1/data`：

- 网页读取的路径是 `/web/read`，每次只选择一种输出格式。
- 联网问答返回 `status: "ok"`，只支持非流式 JSON。
- PPT 生成结果通过 **POST** `/tasks/{task_id}/historical` 查询。
- PPT 创建结果的标识位于 JSON 根层级。需要同时保存 `task_id` 和 `ppt_business_id`。
- 生成的 PPT 七天后过期，需要在到期前导出并保存文件。

这组 API 不包含全部 `/v2` 工作流。例如 LiveDoc 增删改查、Mindmap 和 SuperAgent 仍按原 [Felo APIs 文档](https://openapi.felo.ai/zh-CN/docs/api-reference/felo-apis.md)接入，使用 Pro 积分。

## 接口契约与当前价格

- [公开 OpenAPI 定义](https://openapi.felo.ai/api/v1/data/openapi.json)：完整字段与响应结构。
- [OpenAPI YAML 定义](https://openapi.felo.ai/api/v1/data/openapi.yaml)：适用于需要 YAML 格式的工具。
- [当前价格表](https://openapi.felo.ai/api/v1/data/prices)：操作 ID、计费单位与当前单价。

这些资源无需密钥即可读取。加入自动重试逻辑前，请先阅读[计费与错误处理](https://openapi.felo.ai/zh-CN/docs/data-api/guides/felo-billing.md)。