# Felo API 設定

在 Data API 中設定 Felo 端點以進行搜尋、網頁內容、X 資料與簡報，並使用平台餘額。

Felo 是 [Data API](https://openapi.felo.ai/zh-TW/docs/data-api) 中的一個供應商，提供網頁搜尋、網頁讀取、X 資料、以搜尋為基礎的答案與簡報。你可以在相關的 Data API 分類中找到每個 Felo 端點，並與其他供應商一起並列顯示。

這些端點使用 **平台餘額** 與 `/api/v1/data` 前綴。本指南說明驗證、你的第一個請求，以及在哪裡找到計費規則。

若要使用 Felo Pro 點數，請參閱[既有的 Felo APIs](https://openapi.felo.ai/zh-TW/docs/api-reference/felo-apis.md)。平台餘額與 Pro 點數是分開的。

## 發出第一個請求

1. 在 [Console → API Keys](https://openapi.felo.ai/console/api-keys) 建立金鑰。
2. 在 [Console → Billing](https://openapi.felo.ai/console/billing) 查看或加值你的 **平台餘額**。
3. 在你的伺服器或本機 shell 中設定金鑰：

```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":"What is retrieval augmented generation?","count":3}'
```

HTTP 200 會在 JSON 根層回傳一個包含頁面標題、連結與摘要的 `resources` 陣列，以及 `total`。它不會產生對話式答案；若要產生答案，請使用[Chat](https://openapi.felo.ai/zh-TW/docs/data-api/guides/felo-chat.md)。

## 探索 API

| 指南 | 操作 | 你會收到什麼 | 計費單位 |
|---|---|---|---|
| [網頁搜尋](https://openapi.felo.ai/zh-TW/docs/data-api/guides/felo-web-search.md) | 搜尋網頁 | 頁面標題、連結與摘要 | 請求 |
| [網頁讀取](https://openapi.felo.ai/zh-TW/docs/data-api/guides/felo-web-read.md) | 讀取 URL | Markdown、文字、HTML 或截圖 | 請求 |
| [X 資料](https://openapi.felo.ai/zh-TW/docs/data-api/guides/felo-x-data.md) | 個人檔案、使用者搜尋、使用者貼文、貼文搜尋、回覆 | 結構化的使用者與貼文，並在支援時提供分頁 | 回傳結果 |
| [聯網問答](https://openapi.felo.ai/zh-TW/docs/data-api/guides/felo-chat.md) | 回答問題 | 答案與網頁來源 | 請求 |
| [PPT](https://openapi.felo.ai/zh-TW/docs/data-api/guides/felo-ppt.md) | 建立、狀態、結果、匯出、匯出狀態、刪除 | 生成任務與可下載的 PPTX | 生成頁面；匯出另行計費 |
| [計費與錯誤](https://openapi.felo.ai/zh-TW/docs/data-api/guides/felo-billing.md) | 共用整合指南 | 價格、餘額處理與重試規則 | — |

這些指南合計共有 **14 個核心操作**。如果 PPT 建立回傳 `stream_key`，[PPT 指南](https://openapi.felo.ai/zh-TW/docs/data-api/guides/felo-ppt.md#透過-sse-讀取生成事件) 也會說明如何以 SSE 讀取生成事件。狀態與結果查詢、匯出狀態查詢以及刪除都不會產生新的費用。

## 在移轉既有整合之前

請使用你實際呼叫的端點所對應的指南。將 `/v2` 替換為 `/api/v1/data` 並不代表完整遷移：

- Web Read 使用 `/web/read`，每次請求只支援一種輸出格式。
- Chat 會回傳 `status: "ok"`；它僅支援非串流 JSON。
- PPT 結果使用 **POST** `/tasks/{task_id}/historical`。
- PPT 建立會在 JSON 根層回傳識別碼。請同時儲存 `task_id` 與 `ppt_business_id`。
- 已生成的 PPT 會在七天後過期。請在過期前匯出並儲存檔案。

本文未記錄每個 `/v2` 工作流程的原生 OpenAPI 對應，例如 LiveDoc CRUD、Mindmap 或 SuperAgent。請繼續使用它們的 [Felo APIs 指南](https://openapi.felo.ai/zh-TW/docs/api-reference/felo-apis.md) 與 Pro 點數計費。

## 合約與目前價格

- [已公布的 OpenAPI schema](https://openapi.felo.ai/api/v1/data/openapi.json) — 欄位定義與回應 schema。
- [OpenAPI YAML schema](https://openapi.felo.ai/api/v1/data/openapi.yaml) — 適用於接受 YAML 的工具。
- [目前價格](https://openapi.felo.ai/api/v1/data/prices) — 操作 ID、計費單位與目前費率。

這些資源是公開的，不需要金鑰即可讀取。在加入自動重試之前，請先參閱[計費與錯誤](https://openapi.felo.ai/zh-TW/docs/data-api/guides/felo-billing.md)。