> For the complete documentation index, see [llms.txt](https://developer.eagle.cool/web-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.eagle.cool/web-api/zh-tw/get-started/readme.md).
# 簡介
歡迎閱讀 **Eagle Web API V2** 文件。此 API 允許任何 HTTP 客戶端 — 腳本、應用程式、瀏覽器擴充功能、自動化工具 — 透過本機 HTTP 伺服器與 Eagle 應用程式進行互動。
{% hint style="info" %}
**在找 V1 API？** 舊版 V1 API 文件可以在 找到。V2 基於 Plugin API 的能力，提供了更全面的功能集。
{% endhint %}
{% hint style="warning" %}
**版本要求：** V2 Web API 需要 **Eagle 4.0 Build 21** 或更新版本。
{% endhint %}
***
## Web API 與 Plugin API
Eagle 為開發者提供兩種不同的 API：
* **Web API**（即本文件）— 一套 RESTful HTTP API，用於建構在 Eagle 應用程式**外部**運行的工具、服務、腳本或整合方案。適合開發瀏覽器擴充套件、自動化工作流程、第三方應用程式，或任何獨立於 Eagle 運行的工具。
* [**Plugin API**](https://developer.eagle.cool/plugin-api) — 一套 JavaScript API，用於建構在 Eagle **內部**運行的插件。插件可以直接存取 Eagle 的介面、建立自訂面板、回應使用者操作，並與應用程式深度整合。適合想要擴充 Eagle 內建功能的開發者。
| | Web API | Plugin API |
| ---- | --------------------- | -------------------------------------------------------------------------- |
| 執行位置 | Eagle 外部（任何 HTTP 用戶端） | Eagle 內部（作為插件） |
| 協定 | HTTP REST | JavaScript API |
| 適用場景 | 外部工具、腳本、自動化 | Eagle 插件、自訂面板、介面擴充 |
| 文件 | 本站 | [developer.eagle.cool/plugin-api](https://developer.eagle.cool/plugin-api) |
***
## V2 有什麼新功能
V2 API（`/api/v2/...`）比 V1（`/api/...`）提供了顯著更多的端點，包括：
* **全文搜尋** — 支援進階查詢語法（AND、OR、NOT）
* **AI 語義搜尋** — 透過文字描述或圖片相似度進行搜尋
* **標籤管理** — 建立、重新命名、合併標籤及管理標籤群組
* **資料夾管理** — 建立、移動及整理資料夾
* **自動分頁** — 所有列表端點預設都會回傳分頁結果，確保效能
* [**API Playground**](/web-api/zh-tw/get-started/playground.md) — 內建互動式測試工具，直接在瀏覽器中測試所有端點
***
## 前置條件
Eagle 是一個本機應用程式 — API 伺服器會在 Eagle 應用程式開啟時自動啟動。**您必須先執行 Eagle** 才能存取任何 API 端點。
***
## 基礎 URL
```
http://localhost:41595/api/v2/
```
Eagle API 伺服器預設在連接埠 **41595** 上運行。所有 V2 端點都帶有 `/api/v2/` 前綴。
***
## 身份驗證
### 本機存取（localhost）
如果您從 Eagle 執行的同一台電腦發送請求，**不需要身份驗證**。來自 `localhost`、`127.0.0.1` 或 `0.0.0.0` 的請求會自動受信任 — 您可以直接開始呼叫 API。
```javascript
// 本機存取 — 不需要 token
await fetch("http://localhost:41595/api/v2/library/info").then(r => r.json());
```
### 遠端存取（區域網路 / 網路）
如果您想從區域網路中的另一台裝置（例如手機、平板電腦或另一台電腦）呼叫 Eagle API，您必須在每個請求中附帶 **API Token**。
#### 如何取得您的 API Token
1. 開啟 Eagle，前往**偏好設定**（設定）
2. 點擊左側邊欄中的**開發者**
3. 您的 **API Token** 會顯示在頁面頂部
4. 點擊 token 旁的複製按鈕即可複製到剪貼簿
您也可以點擊**重新產生 Token** 隨時產生新的 token。請注意，重新產生 token 會使先前的 token 失效。
#### 使用 Token
將 `token` 參數附加到任何請求 URL：
```javascript
// 遠端存取附帶 token
const TOKEN = "f366c476-7533-4f33-b454-2bc720a1d0ea";
await fetch(`http://192.168.1.100:41595/api/v2/library/info?token=${TOKEN}`)
.then(r => r.json());
// 同樣適用於 POST 請求
await fetch(`http://192.168.1.100:41595/api/v2/item/get?token=${TOKEN}`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ tags: ["design"], limit: 20 })
}).then(r => r.json());
```
{% hint style="warning" %}
**請妥善保管您的 token。** 任何擁有您 API Token 的人都可以透過網路存取和修改您的 Eagle 資源庫。請勿公開分享或將其提交到版本控制系統中。
{% endhint %}
***
## 回應格式
所有端點都以 [JSend](https://github.com/omniti-labs/jsend) 格式回傳回應：
**成功：**
```json
{
"status": "success",
"data": { ... }
}
```
**錯誤：**
```json
{
"status": "error",
"message": "Error description"
}
```
***
## 分頁
所有列表端點（`item/get`、`item/query`、`folder/get`、`tag/get` 等）預設回傳分頁結果。
| 參數 | 類型 | 預設值 | 最大值 | 說明 |
| -------- | ------- | ---- | ------ | -------- |
| `offset` | Integer | `0` | — | 要跳過的項目數量 |
| `limit` | Integer | `50` | `1000` | 要回傳的項目數量 |
**分頁回應：**
```json
{
"status": "success",
"data": {
"data": [ ... ],
"total": 8500,
"offset": 100,
"limit": 50
}
}
```
* `total` — 符合條件的項目總數（分頁前）
* `offset` — 使用的偏移量
* `limit` — 使用的限制數量
* `data` — 分頁後的結果陣列
**範例：遍歷所有項目**
```javascript
// 第 1 頁：項目 0-49
const page1 = await fetch("http://localhost:41595/api/v2/item/get?limit=50").then(r => r.json());
// 第 2 頁：項目 50-99
const page2 = await fetch("http://localhost:41595/api/v2/item/get?offset=50&limit=50").then(r => r.json());
// 持續直到 data.data.length < limit（最後一頁）
```
***
## 快速開始
```javascript
// 檢查 Eagle 是否正在執行
await fetch("http://localhost:41595/api/v2/app/info").then(r => r.json());
// 取得資源庫資訊
await fetch("http://localhost:41595/api/v2/library/info").then(r => r.json());
// 列出前 50 個項目
await fetch("http://localhost:41595/api/v2/item/get").then(r => r.json());
// 透過標籤搜尋項目
await fetch("http://localhost:41595/api/v2/item/get", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ tags: ["design"] })
}).then(r => r.json());
// 全文搜尋
await fetch("http://localhost:41595/api/v2/item/query", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ query: "sunset landscape" })
}).then(r => r.json());
// AI 語義搜尋
await fetch("http://localhost:41595/api/v2/aiSearch/searchByText", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ query: "an orange cat", options: { limit: 10 } })
}).then(r => r.json());
```
***
## API 分類
| 分類 | 說明 |
| -------------------------------------------- | ------------- |
| [Item](/web-api/zh-tw/api/item.md) | 查詢、新增、修改及管理項目 |
| [Folder](/web-api/zh-tw/api/folder.md) | 建立、列出及整理資料夾 |
| [Tag](/web-api/zh-tw/api/tag.md) | 列出、重新命名及合併標籤 |
| [Tag Group](/web-api/zh-tw/api/tag-group.md) | 管理標籤群組 |
| [Library](/web-api/zh-tw/api/library.md) | 取得資源庫中繼資料 |
| [App](/web-api/zh-tw/api/app.md) | 應用程式資訊 |
| [AI Search](/web-api/zh-tw/api/ai-search.md) | AI 語義搜尋及以圖搜圖 |
***
## CORS
如果您從網頁呼叫 Eagle API（例如透過 **Tampermonkey** 或 **Violentmonkey** 等使用者腳本管理器），標準的 `fetch` 請求可能會被瀏覽器的跨來源資源共享（CORS）政策阻擋。在這種情況下，請改用 `GM_xmlhttpRequest`：
```javascript
GM_xmlhttpRequest({
method: "GET",
url: "http://localhost:41595/api/v2/item/get",
onload: function (response) {
const data = JSON.parse(response.responseText);
console.log(data);
}
});
```
{% hint style="info" %}
這僅適用於在網頁內執行的腳本。如果您從 Node.js、Electron、瀏覽器擴充功能的背景腳本或直接從 DevTools 呼叫 API，則不受 CORS 限制，可以正常使用 `fetch`。
{% endhint %}
***
## 速率限制
API 呼叫**沒有速率限制**。由於 API 伺服器在您的本機上運行，所有請求都會直接處理，不會有任何節流。但請注意，伺服器的效能取決於您裝置的硬體 — 對非常大的資源庫進行繁重操作可能需要較長的回應時間。