MeowID API 圖文接入教學

準備 MeowID 帳號，以及同一隻貓的兩張不同照片：一張用於登記，另一張用於測試。建議先使用光線充足、只有一隻貓的清晰照片。

流程：建立專案 → 建立貓咪檔案 → 登記參考照片 → 等待完成 → 測試辨識 → 建立 API Key → 呼叫 API。

登記和辨識必須使用同一個專案。API 請求發送至 https://platform.meowid.net。

開啟 MeowID 控制台。已有帳號請登入；新使用者先完成註冊再登入。

在左側導覽的「專案」旁點選加號；若導覽已收合，先點選選單按鈕展開。

輸入專案名稱，例如「貓咪辨識示範」，說明可選填。

進入專案後複製專案 ID，這就是 API 網址中的 YOUR_PROJECT_ID。不同專案的貓咪、圖片與特徵向量彼此隔離。

點選「新增個體」，輸入名稱，例如 Mimi，並保持個體啟用，讓牠可以參與辨識。

性格、備註等自訂資訊可透過後文的 API metadata 欄位儲存。

在個體管理中開啟該貓咪的照片庫，選擇「新增登記圖片」。

選取或拖入 JPEG、PNG、WebP 圖片，確認屬於這隻貓後再上傳。首次建議使用一張清晰的單貓照片；登記成功後再補充同一隻貓的不同角度照片。

不要把不同貓咪的照片登記到同一個個體。

上傳成功只表示圖片已被接收。到專案「任務佇列」找到登記任務，等待 status=completed。

queued 和 running 表示仍在處理；waiting_user 請在控制台選擇目標貓咪；failed 則查看錯誤並修正後重試。

登記完成後再測試辨識。

開啟「個體管理 → 辨識測試」，上傳同一隻貓的另一張照片。範例將返回數量設為 3、拒識閾值設為 0.35。

top_k=3 最多返回三個候選；0.35 僅為範例，請使用自己的照片調整。不同照片有助於測試角度、光線和背景變化。

下圖是歷史結果。56.61% 是相似度顯示，不代表辨識正確率為 56.61%。該任務使用 body 路由，因為未偵測到貓臉；仍可使用全身特徵進行比對。

開啟「API Keys」，確認選取正確專案。建立 Key 時使用容易辨識的名稱，例如 meowid-demo-server。

選擇「自訂」，此辨識範例只保留 recognition:write，並確認其他權限已取消勾選。

可依需求設定有效期限與 IP 白名單。完整 Key 只會顯示一次，請存入伺服器環境變數或密鑰管理系統，不要放入公開前端、截圖或 Git。

替換 YOUR_PROJECT_ID 和 YOUR_API_KEY，並在 query.jpg 所在目錄執行：

curl -sS -X POST "https://platform.meowid.net/v1/projects/YOUR_PROJECT_ID/search?top_k=3&threshold=0.35" -H "Authorization: Bearer YOUR_API_KEY" -F "[email protected];type=image/jpeg"

PowerShell 請使用 curl.exe。使用 PNG 或 WebP 時，請同步更換檔名和 MIME 類型。multipart 欄位名稱固定為 image。不要手動設定整體 multipart 的 Content-Type，curl 會自動產生 boundary。

搜尋介面會等待辨識任務完成後回傳結果。呼叫前請確認額度與計費資訊。

以下為精簡格式示意，並非實際回應：

{
  "cat_count": 1,
  "unknown": false,
  "matches": [{
    "cat_id": "example-cat-id",
    "cat_name": "Mimi",
    "score": 0.91,
    "support": 2
  }]
}

使用候選結果前先檢查 unknown。若為 true，即使仍有候選，也不要自動認定身分。score 是相似度，不是正確機率；support 是支援候選的有效向量數量。

照片中有多隻貓時，請逐一處理 candidates；最外層結果只代表第一隻偵測到的貓。若 cat_count 為 0，不要存取 matches[0]。

若要自動登記，請在 Key 增加 cats:write 和 tasks:read；若同一把 Key 也要辨識，請保留 recognition:write。

含自訂 metadata 的檔案範例：

{
  "name": "Mimi",
  "metadata": {
    "personality": "Friendly, loves sunny spots",
    "notes": "Add fields that suit your application"
  },
  "active": true
}

personality 和 notes 是應用自訂欄位，不是模型推斷的資訊。請使用 cat_id 關聯自己的檔案資料。若任務不在第一頁，增加 offset；waiting_user 請在控制台處理，failed 則查看錯誤。

登記完成後即可新增貓咪與參考照片，不需要重新訓練模型。

完整介面說明請參考開發者文件。