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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.eagle.cool/web-api/zh-tw/api/item.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.