AI Search

AI Search API 提供語義搜尋功能 — 透過文字描述搜尋或尋找視覺上相似的圖片。

需要 AI 搜尋插件。 AI 搜尋功能需要安裝並執行 Eagle AI 搜尋插件。在進行搜尋前，請使用狀態端點確認服務是否可用。

端點概覽

方法	端點	說明
GET	/api/v2/aiSearch/isInstalled	檢查 AI 搜尋是否已安裝
GET	/api/v2/aiSearch/isReady	檢查 AI 搜尋是否已就緒
GET	/api/v2/aiSearch/isStarting	檢查 AI 搜尋是否正在啟動中
GET	/api/v2/aiSearch/isSyncing	檢查 AI 搜尋是否正在同步資料
GET	/api/v2/aiSearch/getSyncStatus	取得詳細的同步狀態
GET	/api/v2/aiSearch/checkServiceHealth	檢查服務健康狀態
POST	/api/v2/aiSearch/searchByText	以文字描述搜尋
POST	/api/v2/aiSearch/searchByBase64	以圖片搜尋（Base64）
POST	/api/v2/aiSearch/searchByItemId	以項目 ID 尋找相似項目

---

狀態端點

GET /api/v2/aiSearch/isInstalled

檢查 AI 搜尋插件是否已安裝。

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

回應：

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

---

GET /api/v2/aiSearch/isReady

檢查 AI 搜尋是否已完全初始化並準備好接受搜尋查詢。

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

回應：

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

---

GET /api/v2/aiSearch/isStarting

檢查 AI 搜尋服務是否正在啟動中。

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

回應：

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

---

GET /api/v2/aiSearch/isSyncing

檢查 AI 搜尋是否正在同步（索引）資源庫資料。

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

回應：

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

---

GET /api/v2/aiSearch/getSyncStatus

取得詳細的同步狀態，包含進度資訊。

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

回應：

{
    "status": "success",
    "data": {
        "isSyncing": false,
        "syncedCount": 12500,
        "totalCount": 12500,
        "progress": 1.0
    }
}

---

GET /api/v2/aiSearch/checkServiceHealth

對 AI 搜尋服務執行健康檢查。

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

回應：

{
    "status": "success",
    "data": {
        "healthy": true
    }
}

---

搜尋端點

POST /api/v2/aiSearch/searchByText

使用自然語言文字描述搜尋項目。AI 模型會找到視覺上或語義上匹配的項目。

請求主體

• query string（必填）— 要搜尋的文字描述

• options Object（可選）

  • limit integer — 最大結果數量（預設值依 AI 搜尋設定而定）

回應

{
    "status": "success",
    "data": {
        "results": [
            {
                "item": {
                    "id": "M3QSGJNQTC2DG",
                    "name": "sunset-beach",
                    "ext": "jpg",
                    "width": 1920,
                    "height": 1080,
                    "tags": ["nature", "sunset"],
                    "star": 4
                },
                "score": 0.892
            },
            {
                "item": {
                    "id": "K7XPWQBN9TC3F",
                    "name": "golden-hour",
                    "ext": "png",
                    "width": 2560,
                    "height": 1440,
                    "tags": ["photography"],
                    "star": 3
                },
                "score": 0.756
            }
        ]
    }
}

範例

// 以文字描述搜尋
await fetch("http://localhost:41595/api/v2/aiSearch/searchByText", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ query: "an orange cat sitting on a windowsill" })
}).then(r => r.json());

// 搜尋並限制結果數量
await fetch("http://localhost:41595/api/v2/aiSearch/searchByText", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        query: "minimalist logo design",
        options: { limit: 20 }
    })
}).then(r => r.json());

---

POST /api/v2/aiSearch/searchByBase64

提供 Base64 編碼的圖片來尋找視覺上相似的項目。

請求主體

• base64 string（必填）— Base64 編碼的圖片資料

• options Object（可選）

  • limit integer — 最大結果數量

回應

與 searchByText 格式相同 — 回傳按相似度排序的 { item, score } 結果陣列。

範例

await fetch("http://localhost:41595/api/v2/aiSearch/searchByBase64", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
        base64: "/9j/4AAQSkZJRg...",
        options: { limit: 10 }
    })
}).then(r => r.json());

---

POST /api/v2/aiSearch/searchByItemId

尋找與資源庫中現有項目視覺上相似的項目。

請求主體

• itemId string（必填）— 要尋找相似項目的項目 ID

• options Object（可選）

  • limit integer — 最大結果數量

回應

與 searchByText 格式相同 — 回傳按相似度排序的 { item, score } 結果陣列。

範例

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

---

建議的工作流程

1. 檢查可用性 — 在搜尋前先呼叫 isInstalled 和 isReady

2. 啟動中請等待 — 如果 isStarting 回傳 true，持續輪詢直到 isReady 變為 true

3. 檢查同步狀態 — 使用 getSyncStatus 確認索引是否為最新

4. 搜尋 — 使用 searchByText 進行描述性搜尋、searchByBase64 進行以圖搜圖、或 searchByItemId 尋找相似項目

// 步驟 1：確認 AI 搜尋已就緒
const { data: isReady } = await fetch("http://localhost:41595/api/v2/aiSearch/isReady")
    .then(r => r.json());

if (isReady) {
    // 步驟 2：執行搜尋
    const results = await fetch("http://localhost:41595/api/v2/aiSearch/searchByText", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ query: "sunset landscape", options: { limit: 10 } })
    }).then(r => r.json());

    console.log(results.data.results);
}