MeowID API 画像付き導入ガイド

MeowID アカウントと、同じ猫を写した異なる写真を 2 枚用意します。1 枚は登録用、もう 1 枚はテスト用です。最初は明るく、猫が 1 匹だけ写った写真を使いましょう。

手順：プロジェクト作成 → 猫プロフィール作成 → 参考写真登録 → 完了待ち → 認識テスト → API Key 作成 → API 呼び出し。

登録と認識には同じプロジェクトを使用します。API の接続先は https://platform.meowid.net です。

MeowID コンソールを開きます。アカウントがある場合はログインし、新規の場合は登録してからログインしてください。

左側ナビゲーションの「プロジェクト」の横にあるプラスを選択します。ナビゲーションが折りたたまれている場合は、メニューボタンで開きます。

プロジェクト名を入力します。説明は任意です。

プロジェクトを開いて ID をコピーします。API URL の YOUR_PROJECT_ID に指定します。猫、画像、特徴ベクトルはプロジェクトごとに分離されます。

「個体を追加」を選び、Mimi などの名前を入力します。認識に利用できるよう、個体を有効のままにします。

性格やメモなどの独自属性は、後述する API の metadata で保存できます。

個体管理から対象の猫の写真ライブラリを開き、「登録画像を追加」を選びます。

JPEG、PNG、WebP を選択またはドラッグし、対象の猫の写真であることを確認してアップロードします。最初は猫が 1 匹だけ写った鮮明な写真を使い、登録完了後に同じ猫の別角度を追加してください。

異なる猫の写真を同じプロフィールに登録しないでください。

アップロード成功は画像の受け付けを意味し、処理完了とは限りません。プロジェクトのタスクキューで登録タスクを確認し、status=completed を待ちます。

queued / running は処理中です。waiting_user の場合はコンソールで対象の猫を選択します。failed の場合はエラーを確認してから再試行してください。

登録完了後に認識テストを行います。

「個体管理 → 認識テスト」を開き、同じ猫の別の写真をアップロードします。例では返却数を 3、拒否しきい値を 0.35 に設定します。

top_k=3 は候補を最大 3 件返します。0.35 は例示値です。実際の写真で調整してください。角度、光、背景の変化を含む別写真でテストすると効果的です。

下の画面は過去の結果です。56.61% は類似度の表示であり、正解率ではありません。このタスクでは顔が検出されず body ルートで全身特徴を照合しています。

「API Keys」を開き、対象プロジェクトが選択されていることを確認します。用途が分かる名前を付けて Key を作成してください。

「カスタム」を選び、認識のみの例では 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 を生成させます。

検索 API は認識処理の完了を待って結果を返します。利用前に残高と料金を確認してください。

以下は形式の簡略例で、実際のレスポンスそのものではありません。

{
  "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 はアプリ側で定義する metadata で、モデルの推論結果ではありません。cat_id で自分のプロフィールと関連付けます。タスクが 1 ページ目にない場合は offset を増やしてください。waiting_user はコンソールで処理し、failed はエラーを確認します。

登録完了後は、モデルを再学習せずに猫や参考写真を追加できます。

詳細は開発者ドキュメントを参照してください。