> 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/api/item.md).

# Item

## 端點概覽

| 方法   | 端點                                | 說明              |
| ---- | --------------------------------- | --------------- |
| 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 <a href="#list" id="list"></a>

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

### 查詢參數

* `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`

### 回應

```json
{
    "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
    }
}
```

### 範例

```javascript
// 列出前 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 <a href="#list-post" id="list-post"></a>

與 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`

### 範例

```javascript
// 以標籤篩選
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());
```

```javascript
// 搭配智慧型資料夾篩選
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());
```

{% hint style="info" %}
**效能提示：** 使用 `fields` 參數只回傳您需要的資料。在處理大型資源庫時，這能顯著提升回應速度。
{% endhint %}

***

## POST /api/v2/item/query <a href="#query" id="query"></a>

跨項目名稱、標籤、註解、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` |

### 範例

```javascript
// 簡單搜尋
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 <a href="#count" id="count"></a>

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

### 回應

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

### 範例

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

***

## POST /api/v2/item/add <a href="#add" id="add"></a>

新增項目到 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

### 範例

```javascript
// 從 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：

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

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

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

***

## POST /api/v2/item/update <a href="#update" id="update"></a>

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

### 請求主體

* `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（可選）— 移至垃圾桶 / 從垃圾桶還原

### 回應

回傳更新後的項目物件。

### 範例

```javascript
// 更新項目名稱和標籤
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 <a href="#set-thumbnail" id="set-thumbnail"></a>

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

### 請求主體

* `itemId` string（必填）— 項目 ID
* `filePath` string（必填）— 縮圖圖片的路徑

### 範例

```javascript
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());
```

{% hint style="info" %}
此操作為非同步。API 會等待最多 10 秒讓縮圖產生完成後再回應。
{% endhint %}

***

## POST /api/v2/item/refreshThumbnail <a href="#refresh-thumbnail" id="refresh-thumbnail"></a>

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

### 請求主體

* `itemId` string（必填）— 項目 ID

### 範例

```javascript
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 <a href="#get-comments" id="get-comments"></a>

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

{% hint style="info" %}
\*\*版本需求：\*\*此端點需要 **Eagle 4.0 Build 22** 或更高版本。
{% endhint %}

### 查詢參數

* `id` string（必填）— 項目 ID

### 回應

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

### 範例

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

***

## POST /api/v2/item/addComment <a href="#add-comment" id="add-comment"></a>

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

* **圖片框選標註** — 提供 `x`、`y`、`width`、`height` 來標記圖片上的區域
* **影片時間軸註解** — 提供 `duration` 來標記影片時間軸上的時間點

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

{% hint style="info" %}
\*\*版本需求：\*\*此端點需要 **Eagle 4.0 Build 22** 或更高版本。
{% endhint %}

### 請求主體

* `id` string（必填）— 項目 ID
* `annotation` string（可選）— 標註文字
* `x` number（可選）— 框選 X 座標（圖片標註）
* `y` number（可選）— 框選 Y 座標（圖片標註）
* `width` number（可選）— 框選寬度，必須 > 0（圖片標註）
* `height` number（可選）— 框選高度，必須 > 0（圖片標註）
* `duration` number（可選）— 影片時間戳（秒），必須 >= 0（影片註解）

{% hint style="warning" %}
必須提供 `duration`（影片）或完整的 `x`/`y`/`width`/`height`（圖片）。同時提供或都不提供將回傳錯誤。
{% endhint %}

### 範例

```javascript
// 新增圖片框選標註
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 <a href="#update-comment" id="update-comment"></a>

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

{% hint style="info" %}
\*\*版本需求：\*\*此端點需要 **Eagle 4.0 Build 22** 或更高版本。
{% endhint %}

### 請求主體

* `id` string（必填）— 項目 ID
* `commentId` string（必填）— 要更新的標註 ID
* `annotation` string（可選）— 新的標註文字
* `x` number（可選）— 新的 X 座標（僅限圖片標註）
* `y` number（可選）— 新的 Y 座標（僅限圖片標註）
* `width` number（可選）— 新的寬度，必須 > 0（僅限圖片標註）
* `height` number（可選）— 新的高度，必須 > 0（僅限圖片標註）
* `duration` number（可選）— 新的時間戳，必須 >= 0（僅限影片註解）

{% hint style="warning" %}
圖片標註只能更新 `x`/`y`/`width`/`height`，影片註解只能更新 `duration`。跨類型更新會回傳錯誤。
{% endhint %}

### 範例

```javascript
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 <a href="#remove-comment" id="remove-comment"></a>

從項目中移除標註。

{% hint style="info" %}
\*\*版本需求：\*\*此端點需要 **Eagle 4.0 Build 22** 或更高版本。
{% endhint %}

### 請求主體

* `id` string（必填）— 項目 ID
* `commentId` string（必填）— 要移除的標註 ID

### 範例

```javascript
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 屬性 <a href="#properties" id="properties"></a>

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   | 是否停用雙擊預覽  |