# AI Search
{% hint style="info" %}
**需要** [**AI Search**](https://eagle.cool/support/article/ai-search) **插件。** AI 搜尋功能需要安裝並執行 Eagle AI 搜尋插件。在進行搜尋前，請使用狀態端點確認服務是否可用。
{% endhint %}
## 端點概覽
| 方法 | 端點 | 說明 |
| ---- | ------------------------------------- | ---------------- |
| 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 搜尋插件是否已安裝。
```javascript
await fetch("http://localhost:41595/api/v2/aiSearch/isInstalled").then(r => r.json());
```
**回應：**
```json
{
"status": "success",
"data": true
}
```
***
### GET /api/v2/aiSearch/isReady
檢查 AI 搜尋是否已完全初始化並準備好接受搜尋查詢。
```javascript
await fetch("http://localhost:41595/api/v2/aiSearch/isReady").then(r => r.json());
```
**回應：**
```json
{
"status": "success",
"data": true
}
```
***
### GET /api/v2/aiSearch/isStarting
檢查 AI 搜尋服務是否正在啟動中。
```javascript
await fetch("http://localhost:41595/api/v2/aiSearch/isStarting").then(r => r.json());
```
**回應：**
```json
{
"status": "success",
"data": false
}
```
***
### GET /api/v2/aiSearch/isSyncing
檢查 AI 搜尋是否正在同步（索引）資源庫資料。
```javascript
await fetch("http://localhost:41595/api/v2/aiSearch/isSyncing").then(r => r.json());
```
**回應：**
```json
{
"status": "success",
"data": false
}
```
***
### GET /api/v2/aiSearch/getSyncStatus
取得詳細的同步狀態，包含進度資訊。
```javascript
await fetch("http://localhost:41595/api/v2/aiSearch/getSyncStatus").then(r => r.json());
```
**回應：**
```json
{
"status": "success",
"data": {
"isSyncing": false,
"syncedCount": 12500,
"totalCount": 12500,
"progress": 1.0
}
}
```
***
### GET /api/v2/aiSearch/checkServiceHealth
對 AI 搜尋服務執行健康檢查。
```javascript
await fetch("http://localhost:41595/api/v2/aiSearch/checkServiceHealth").then(r => r.json());
```
**回應：**
```json
{
"status": "success",
"data": {
"healthy": true
}
}
```
***
## 搜尋端點
### POST /api/v2/aiSearch/searchByText
使用自然語言文字描述搜尋項目。AI 模型會找到視覺上或語義上匹配的項目。
#### 請求主體
* `query` string（必填）— 要搜尋的文字描述
* `options` Object（可選）
* `limit` integer — 最大結果數量（預設值依 AI 搜尋設定而定）
#### 回應
```json
{
"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
}
]
}
}
```
#### 範例
```javascript
// 以文字描述搜尋
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 }` 結果陣列。
#### 範例
```javascript
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 }` 結果陣列。
#### 範例
```javascript
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` 尋找相似項目
```javascript
// 步驟 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);
}
```
---
# 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/ai-search.md?ask=
```
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.