Item

Item API 允許您查詢、新增、修改及管理 Eagle 資源庫中的項目。

端點概覽

方法	端點	說明
GET	/api/v2/item/get	以篩選條件列出項目
POST	/api/v2/item/get	以篩選條件列出項目（請求主體）
POST	/api/v2/item/query	全文搜尋
GET	/api/v2/item/countAll	計算所有項目數量
POST	/api/v2/item/add	新增項目
POST	/api/v2/item/update	更新項目
POST	/api/v2/item/setCustomThumbnail	設定自訂縮圖
POST	/api/v2/item/refreshThumbnail	重新整理項目縮圖

---

GET /api/v2/item/get

以可選的篩選條件列出項目。回傳分頁結果。

查詢參數

• id string（可選）— 以 ID 回傳單一項目

• ids string（可選）— 以逗號分隔的項目 ID

• isSelected boolean（可選）— 回傳目前選取的項目

• isUntagged boolean（可選）— 回傳沒有標籤的項目

• isUnfiled boolean（可選）— 回傳不在任何資料夾中的項目

• keywords string（可選）— 以關鍵字篩選（逗號分隔）

• tags string（可選）— 以標籤篩選（逗號分隔）

• folders string（可選）— 以資料夾 ID 篩選（逗號分隔）

• ext string（可選）— 以副檔名篩選（例如 jpg、png）

• annotation string（可選）— 以註解文字篩選

• rating integer（可選）— 以評分篩選（0–5）

• url string（可選）— 以來源 URL 篩選

• shape string（可選）— 以形狀篩選：square、portrait、panoramic-portrait、landscape、panoramic-landscape

• fields string（可選）— 以逗號分隔的回傳欄位列表（可提升效能）

• offset integer（可選）— 分頁偏移量，預設 0

• limit integer（可選）— 分頁限制，預設 50，最大 1000

回應

{
    "status": "success",
    "data": {
        "data": [
            {
                "id": "M3QSGJNQTC2DG",
                "name": "sunset-photo",
                "ext": "jpg",
                "width": 1920,
                "height": 1080,
                "url": "https://example.com/photo.jpg",
                "tags": ["nature", "sunset"],
                "folders": ["FOLDER_ID_1"],
                "star": 4,
                "annotation": "Beautiful sunset at the beach",
                "modificationTime": 1700000000000
            }
        ],
        "total": 1250,
        "offset": 0,
        "limit": 50
    }
}

範例

// 列出前 50 個項目（預設）
await fetch("http://localhost:41595/api/v2/item/get").then(r => r.json());

// 以 ID 取得單一項目
await fetch("http://localhost:41595/api/v2/item/get?id=M3QSGJNQTC2DG").then(r => r.json());

// 以副檔名篩選並分頁
await fetch("http://localhost:41595/api/v2/item/get?ext=png&offset=0&limit=100").then(r => r.json());

// 只回傳特定欄位以提升效能
await fetch("http://localhost:41595/api/v2/item/get?fields=id,name,tags").then(r => r.json());

---

POST /api/v2/item/get

與 GET 相同，但接受 JSON 主體中的篩選參數。適用於包含陣列的複雜查詢。

請求主體

• id string（可選）— 項目 ID

• ids string[]（可選）— 項目 ID 陣列

• isSelected boolean（可選）— 目前選取的項目

• isUntagged boolean（可選）— 沒有標籤的項目

• isUnfiled boolean（可選）— 不在任何資料夾中的項目

• keywords string[]（可選）— 要匹配的關鍵字

• tags string[]（可選）— 要匹配的標籤

• folders string[]（可選）— 要匹配的資料夾 ID

• smartFolders string[]（可選）— 以智慧型資料夾 ID 篩選（OR 邏輯，符合任一即包含）

• ext string（可選）— 副檔名

• annotation string（可選）— 註解文字

• rating integer（可選）— 評分（0–5）

• url string（可選）— 來源 URL

• shape string（可選）— 圖片形狀

• fields string[]（可選）— 要回傳的欄位

• offset integer（可選）— 分頁偏移量，預設 0

• limit integer（可選）— 分頁限制，預設 50，最大 1000

範例

// 以標籤篩選
await fetch("http://localhost:41595/api/v2/item/get", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        tags: ["design", "inspiration"],
        limit: 20
    })
}).then(r => r.json());

// 以多個 ID 取得項目
await fetch("http://localhost:41595/api/v2/item/get", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        ids: ["ITEM_ID_1", "ITEM_ID_2", "ITEM_ID_3"]
    })
}).then(r => r.json());

// 篩選特定資料夾中的 JPG 檔案，只回傳 id 和 name
await fetch("http://localhost:41595/api/v2/item/get", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        ext: "jpg",
        folders: ["FOLDER_ID"],
        fields: ["id", "name", "tags"],
        offset: 0,
        limit: 100
    })
}).then(r => r.json());

// 搭配智慧型資料夾篩選
await fetch("http://localhost:41595/api/v2/item/get", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        smartFolders: ["SMART_FOLDER_ID"],
        tags: ["cat"],
        limit: 20
    })
}).then(r => r.json());

效能提示： 使用 fields 參數只回傳您需要的資料。在處理大型資源庫時，這能顯著提升回應速度。

---

POST /api/v2/item/query

跨項目名稱、標籤、註解、URL、資料夾名稱等進行全文搜尋。支援進階查詢語法。回傳分頁結果。

請求主體

• query string — 搜尋查詢字串

• offset integer（可選）— 分頁偏移量，預設 0

• limit integer（可選）— 分頁限制，預設 50，最大 1000

查詢語法

語法	說明	範例
word	必須包含該詞	cat
a b	必須同時包含（AND）	cat dog
a OR b	包含其中之一（OR）	cat OR dog
a || b	包含其中之一（OR）	cat || dog
-word	必須不包含	cat -dog
"phrase"	精確片語匹配	"orange cat"
(a OR b) c	分組	(cat OR dog) cute

範例

// 簡單搜尋
await fetch("http://localhost:41595/api/v2/item/query", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ query: "sunset" })
}).then(r => r.json());

// 進階搜尋：包含 "cat" 或 "dog" 但不包含 "cartoon" 的項目
await fetch("http://localhost:41595/api/v2/item/query", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        query: "(cat OR dog) -cartoon",
        limit: 20
    })
}).then(r => r.json());

// 分頁瀏覽搜尋結果
await fetch("http://localhost:41595/api/v2/item/query", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ query: "design", offset: 50, limit: 50 })
}).then(r => r.json());

---

GET /api/v2/item/countAll

回傳資源庫中的項目總數。

回應

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

範例

await fetch("http://localhost:41595/api/v2/item/countAll").then(r => r.json());

---

POST /api/v2/item/add

新增項目到 Eagle。支援從 URL、Base64 資料、本機檔案路徑或書籤新增。

請求主體

• id string（可選）— 自訂項目 ID

• name string（可選）— 項目名稱

• tags string[]（可選）— 要指派的標籤

• folders string[]（可選）— 要加入的資料夾 ID

• annotation string（可選）— 項目註解

• website string（可選）— 來源網站 URL

另外加上以下其中一項：

• url string — 要下載的圖片 URL

• base64 string — Base64 編碼的圖片資料

• path string — 要匯入的本機檔案路徑

• bookmarkURL string — 要加為書籤的 URL

範例

// 從 URL 新增
await fetch("http://localhost:41595/api/v2/item/add", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        url: "https://example.com/photo.jpg",
        name: "Example Photo",
        tags: ["downloaded", "example"],
        folders: ["FOLDER_ID"]
    })
}).then(r => r.json());

// 從本機檔案路徑新增
await fetch("http://localhost:41595/api/v2/item/add", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        path: "C:\\Users\\User\\Downloads\\design.png",
        name: "My Design",
        tags: ["design"]
    })
}).then(r => r.json());

// 新增書籤
await fetch("http://localhost:41595/api/v2/item/add", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        bookmarkURL: "https://www.example.com",
        name: "Example Site",
        tags: ["bookmark"]
    })
}).then(r => r.json());

// 批量新增多個項目（最多 1000 個）
await fetch("http://localhost:41595/api/v2/item/add", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        items: [
            { url: "https://example.com/photo1.jpg", name: "Photo 1" },
            { path: "C:\\Users\\User\\Downloads\\design.png", name: "Design" },
            { bookmarkURL: "https://www.example.com", name: "Bookmark" }
        ]
    })
}).then(r => r.json());

批量模式

傳入 items 陣列可一次新增多個項目（最多 1000 個）。陣列中每個物件的格式與單一模式相同，支援混合 path、url、bookmarkURL、base64。

回應

單一模式回傳新建項目的 ID：

{
    "status": "success",
    "data": { "id": "M3QSGJNQTC2DG" }
}

批量模式回傳所有新建項目的 ID：

{
    "status": "success",
    "data": { "ids": ["ITEM_ID_1", "ITEM_ID_2", "ITEM_ID_3"] }
}

---

POST /api/v2/item/update

更新現有項目的中繼資料。只有您包含的欄位會被修改。

請求主體

• id string（必填）— 要更新的項目 ID

可修改的欄位：

• name string（可選）— 新名稱

• tags string[]（可選）— 替換標籤

• folders string[]（可選）— 替換資料夾指派

• annotation string（可選）— 新註解

• url string（可選）— 新來源 URL

• star integer（可選）— 評分，0–5

• modificationTime integer（可選）— 修改時間戳記

• noThumbnail boolean（可選）— 標記為沒有縮圖

• noPreview boolean（可選）— 標記為不可預覽

• isDeleted boolean（可選）— 移至垃圾桶 / 從垃圾桶還原

回應

回傳更新後的項目物件。

範例

// 更新項目名稱和標籤
await fetch("http://localhost:41595/api/v2/item/update", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        id: "M3QSGJNQTC2DG",
        name: "Updated Name",
        tags: ["tag1", "tag2"],
        star: 5
    })
}).then(r => r.json());

// 將項目移至垃圾桶
await fetch("http://localhost:41595/api/v2/item/update", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        id: "M3QSGJNQTC2DG",
        isDeleted: true
    })
}).then(r => r.json());

---

POST /api/v2/item/setCustomThumbnail

從本機圖片檔案為項目設定自訂縮圖。

請求主體

• itemId string（必填）— 項目 ID

• filePath string（必填）— 縮圖圖片的路徑

範例

await fetch("http://localhost:41595/api/v2/item/setCustomThumbnail", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        itemId: "M3QSGJNQTC2DG",
        filePath: "C:\\Users\\User\\thumbnails\\custom.png"
    })
}).then(r => r.json());

此操作為非同步。API 會等待最多 10 秒讓縮圖產生完成後再回應。

---

POST /api/v2/item/refreshThumbnail

重新產生項目的縮圖，同時更新檔案大小、尺寸和色彩資訊。

請求主體

• itemId string（必填）— 項目 ID

範例

await fetch("http://localhost:41595/api/v2/item/refreshThumbnail", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ itemId: "M3QSGJNQTC2DG" })
}).then(r => r.json());

---

GET /api/v2/item/getComments

取得項目的所有標註（註解）。回傳圖片框選標註或影片時間軸註解。

**版本需求：**此端點需要 Eagle 4.0 Build 22 或更高版本。

查詢參數

• id string（必填）— 項目 ID

回應

{
    "status": "success",
    "data": [
        {
            "id": "MN3DZC0R7XYSZ",
            "x": 324,
            "y": 810,
            "width": 194,
            "height": 208,
            "annotation": "臉部區域",
            "lastModified": 1774282485915
        }
    ]
}

範例

await fetch("http://localhost:41595/api/v2/item/getComments?id=M3QSGJNQTC2DG")
    .then(r => r.json());

---

POST /api/v2/item/addComment

新增標註至項目。支援兩種類型：

• 圖片框選標註 — 提供 x、y、width、height 來標記圖片上的區域

• 影片時間軸註解 — 提供 duration 來標記影片時間軸上的時間點

伺服器會自動產生 id 和 lastModified 欄位。

**版本需求：**此端點需要 Eagle 4.0 Build 22 或更高版本。

請求主體

• id string（必填）— 項目 ID

• annotation string（可選）— 標註文字

• x number（可選）— 框選 X 座標（圖片標註）

• y number（可選）— 框選 Y 座標（圖片標註）

• width number（可選）— 框選寬度，必須 > 0（圖片標註）

• height number（可選）— 框選高度，必須 > 0（圖片標註）

• duration number（可選）— 影片時間戳（秒），必須 >= 0（影片註解）

必須提供 duration（影片）或完整的 x/y/width/height（圖片）。同時提供或都不提供將回傳錯誤。

範例

// 新增圖片框選標註
await fetch("http://localhost:41595/api/v2/item/addComment", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        id: "M3QSGJNQTC2DG",
        x: 350, y: 480, width: 380, height: 400,
        annotation: "白色毛絨玩具的臉"
    })
}).then(r => r.json());

// 新增影片時間軸註解
await fetch("http://localhost:41595/api/v2/item/addComment", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        id: "VIDEO_ITEM_ID",
        duration: 65.5,
        annotation: "重要場景"
    })
}).then(r => r.json());

---

POST /api/v2/item/updateComment

更新現有標註。僅更新提供的欄位；lastModified 會自動更新。

**版本需求：**此端點需要 Eagle 4.0 Build 22 或更高版本。

請求主體

• id string（必填）— 項目 ID

• commentId string（必填）— 要更新的標註 ID

• annotation string（可選）— 新的標註文字

• x number（可選）— 新的 X 座標（僅限圖片標註）

• y number（可選）— 新的 Y 座標（僅限圖片標註）

• width number（可選）— 新的寬度，必須 > 0（僅限圖片標註）

• height number（可選）— 新的高度，必須 > 0（僅限圖片標註）

• duration number（可選）— 新的時間戳，必須 >= 0（僅限影片註解）

圖片標註只能更新 x/y/width/height，影片註解只能更新 duration。跨類型更新會回傳錯誤。

範例

await fetch("http://localhost:41595/api/v2/item/updateComment", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        id: "M3QSGJNQTC2DG",
        commentId: "MN3DZC0R7XYSZ",
        annotation: "更新後的標註文字"
    })
}).then(r => r.json());

---

POST /api/v2/item/removeComment

從項目中移除標註。

**版本需求：**此端點需要 Eagle 4.0 Build 22 或更高版本。

請求主體

• id string（必填）— 項目 ID

• commentId string（必填）— 要移除的標註 ID

範例

await fetch("http://localhost:41595/api/v2/item/removeComment", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        id: "M3QSGJNQTC2DG",
        commentId: "MN3DZC0R7XYSZ"
    })
}).then(r => r.json());

---

Item 屬性

API 回傳的項目包含以下屬性：

屬性	類型	說明
id	string	唯一項目 ID
name	string	項目名稱
ext	string	副檔名
width	integer	圖片寬度（像素）
height	integer	圖片高度（像素）
url	string	來源 URL
isDeleted	boolean	項目是否在垃圾桶中
annotation	string	項目註解 / 筆記
tags	string[]	標籤名稱陣列
folders	string[]	資料夾 ID 陣列
palettes	Object[]	色彩資訊
size	integer	檔案大小（位元組）
star	integer	評分（0–5）
modificationTime	integer	最後修改時間戳記
noThumbnail	boolean	檔案是否沒有縮圖
noPreview	boolean	是否停用雙擊預覽