簡介

Eagle Web API V2 提供了完整的 RESTful HTTP API，用於與 Eagle 應用程式互動，讓外部工具和腳本能夠以程式化方式管理您的素材庫。

歡迎閱讀 Eagle Web API V2 文件。此 API 允許任何 HTTP 客戶端 — 腳本、應用程式、瀏覽器擴充功能、自動化工具 — 透過本機 HTTP 伺服器與 Eagle 應用程式進行互動。

在找 V1 API？ 舊版 V1 API 文件可以在 https://api.eagle.cool/ 找到。V2 基於 Plugin API 的能力，提供了更全面的功能集。

版本要求： V2 Web API 需要 Eagle 4.0 Build 21 或更新版本。

---

Web API 與 Plugin API

Eagle 為開發者提供兩種不同的 API：

• Web API（即本文件）— 一套 RESTful HTTP API，用於建構在 Eagle 應用程式外部運行的工具、服務、腳本或整合方案。適合開發瀏覽器擴充套件、自動化工作流程、第三方應用程式，或任何獨立於 Eagle 運行的工具。

• Plugin API — 一套 JavaScript API，用於建構在 Eagle 內部運行的插件。插件可以直接存取 Eagle 的介面、建立自訂面板、回應使用者操作，並與應用程式深度整合。適合想要擴充 Eagle 內建功能的開發者。

	Web API	Plugin API
執行位置	Eagle 外部（任何 HTTP 用戶端）	Eagle 內部（作為插件）
協定	HTTP REST	JavaScript API
適用場景	外部工具、腳本、自動化	Eagle 插件、自訂面板、介面擴充
文件	本站	developer.eagle.cool/plugin-api

---

V2 有什麼新功能

V2 API（/api/v2/...）比 V1（/api/...）提供了顯著更多的端點，包括：

• 全文搜尋 — 支援進階查詢語法（AND、OR、NOT）

• AI 語義搜尋 — 透過文字描述或圖片相似度進行搜尋

• 標籤管理 — 建立、重新命名、合併標籤及管理標籤群組

• 資料夾管理 — 建立、移動及整理資料夾

• 自動分頁 — 所有列表端點預設都會回傳分頁結果，確保效能

• API Playground — 內建互動式測試工具，直接在瀏覽器中測試所有端點

---

前置條件

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。

// 本機存取 — 不需要 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：

// 遠端存取附帶 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());

請妥善保管您的 token。 任何擁有您 API Token 的人都可以透過網路存取和修改您的 Eagle 資源庫。請勿公開分享或將其提交到版本控制系統中。

---

回應格式

所有端點都以 JSend 格式回傳回應：

成功：

{
    "status": "success",
    "data": { ... }
}

錯誤：

{
    "status": "error",
    "message": "Error description"
}

---

分頁

所有列表端點（item/get、item/query、folder/get、tag/get 等）預設回傳分頁結果。

參數	類型	預設值	最大值	說明
offset	Integer	0	—	要跳過的項目數量
limit	Integer	50	1000	要回傳的項目數量

分頁回應：

{
    "status": "success",
    "data": {
        "data": [ ... ],
        "total": 8500,
        "offset": 100,
        "limit": 50
    }
}

• total — 符合條件的項目總數（分頁前）

• offset — 使用的偏移量

• limit — 使用的限制數量

• data — 分頁後的結果陣列

範例：遍歷所有項目

// 第 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（最後一頁）

---

快速開始

// 檢查 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	查詢、新增、修改及管理項目
Folder	建立、列出及整理資料夾
Tag	列出、重新命名及合併標籤
Tag Group	管理標籤群組
Library	取得資源庫中繼資料
App	應用程式資訊
AI Search	AI 語義搜尋及以圖搜圖

---

CORS

如果您從網頁呼叫 Eagle API（例如透過 Tampermonkey 或 Violentmonkey 等使用者腳本管理器），標準的 fetch 請求可能會被瀏覽器的跨來源資源共享（CORS）政策阻擋。在這種情況下，請改用 GM_xmlhttpRequest：

GM_xmlhttpRequest({
    method: "GET",
    url: "http://localhost:41595/api/v2/item/get",
    onload: function (response) {
        const data = JSON.parse(response.responseText);
        console.log(data);
    }
});

這僅適用於在網頁內執行的腳本。如果您從 Node.js、Electron、瀏覽器擴充功能的背景腳本或直接從 DevTools 呼叫 API，則不受 CORS 限制，可以正常使用 fetch。

---

速率限制

API 呼叫沒有速率限制。由於 API 伺服器在您的本機上運行，所有請求都會直接處理，不會有任何節流。但請注意，伺服器的效能取決於您裝置的硬體 — 對非常大的資源庫進行繁重操作可能需要較長的回應時間。