AI Search

AI Search API は、セマンティック検索機能を提供します。テキスト説明による検索や、視覚的に類似した画像の検索が可能です。

AI Search プラグインが必要です。 AI Search 機能を使用するには、Eagle AI Search プラグインがインストールされ、実行されている必要があります。検索を実行する前に、ステータスエンドポイントを使用して利用可能かどうかを確認してください。

エンドポイント一覧

メソッド	エンドポイント	説明
GET	/api/v2/aiSearch/isInstalled	AI Search がインストール済みか確認
GET	/api/v2/aiSearch/isReady	AI Search が準備完了か確認
GET	/api/v2/aiSearch/isStarting	AI Search が起動中か確認
GET	/api/v2/aiSearch/isSyncing	AI Search がデータ同期中か確認
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 Search プラグインがインストールされているかどうかを確認します。

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

レスポンス：

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

---

GET /api/v2/aiSearch/isReady

AI Search が完全に初期化され、検索クエリを受け付ける準備ができているかどうかを確認します。

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

レスポンス：

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

---

GET /api/v2/aiSearch/isStarting

AI Search サービスが現在起動中かどうかを確認します。

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

レスポンス：

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

---

GET /api/v2/aiSearch/isSyncing

AI Search が現在ライブラリデータを同期（インデックス作成）中かどうかを確認します。

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 Search サービスのヘルスチェックを実行します。

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 Search の設定による）

レスポンス

{
    "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. 同期ステータスを確認 -- syncStatus を使用してインデックスが最新であることを確認してください

4. 検索を実行 -- 説明文による検索には searchByText、逆画像検索には searchByBase64、類似アイテム検索には searchByItemId を使用してください

// ステップ 1: AI Search の準備が完了しているか確認
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);
}