開発者向け / OPENAPI v1

あなたのアプリに、
猫を見分ける力を。

Maopu 猫認識 API 導入ガイド

最初の登録画像から個体検索まで。標準 HTTP インターフェースで猫台帳、タスク管理、候補取得を実装できます。

公開ドキュメント・ログイン不要

最初のリクエストの前に

コンソールにログインしてプロジェクトを作成し、完全な UUID をコピーします。
プロジェクト用の API キーを作り、権限を設定します。一度だけ表示される秘密キーを保存してください。
猫の個体を作成し、返された id を保存してから登録画像を送信します。
タスク一覧で登録完了を確認し、検索画像をアップロードして候補を取得します。

実装例の {{base_url}}は HTTPS API のサービスアドレス、 {{api_key}} はプロジェクトのキーです。API アドレスは配備設定またはサービス提供者から取得してください。このサイトは文書の公開用で、/v1 の業務リクエストは処理しません。

cURL の例は Bash の行継続を使います。Windows では Postman の Import → Raw text から読み込み、base_url と api_key を設定し、画像を選び直してください。Python の例は requests と環境変数を設定したサーバー上で実行します。

認証

プロジェクトごとの認証情報

業務 API は Authorization: Bearer mk_live_… またはプロジェクト所有者のログイントークンを受け付けます。キーは一つのプロジェクトに結び付き、権限内のデータにアクセスできます。

Scope	許可される操作
`cats:read`	個体、画像一覧、画像データを取得
`cats:write`	個体と登録画像の管理、メイン画像と登録候補の選択
`recognition:write`	猫の個体検索を実行
`tasks:read`	タスク、結果、統計、プレビュー画像を取得

キーの状態、失効、有効期限、IP 許可リストを認証時に確認します。完全アクセスは四つの権限を含み、作成時の scopes が空配列でも四つすべてが付与されます。タスク再試行は現在 cats:write または recognition:write のいずれかで可能です。

プロジェクト作成・設定、キー管理、ウォレット、請求、使用量の取得には API キーではなくログイントークンが必要です。秘密キーはサーバー側の環境変数に保存してください。

処理フロー

登録は非同期、検索は結果を待機

登録は HTTP 202 と task_id を返します。この段階の vectors_added: 0 は正常です。バックグラウンドの特徴抽出後に検索可能になります。認識リクエストは優先処理され、推論の完了を待って結果を返します。

queued → running → completed
                 → waiting_user → selection → queued
                 → failed → retry → queued

数秒おきに GET /tasks?limit=10&offset=0 を呼び、id で task_id を探します。GET /tasks/ {task_id} という単独の詳細 API はありません。タスクは作成日時の降順です。offset でページ送りし、タスク ID で重複を除きます。

登録画像に複数の猫がいる場合は waiting_user になることがあります。候補画像を確認して selection に candidate_index を送るか、cancel で保留中の登録を中止します。再試行できるのは failed のタスクのみです。

タイムアウトはタスク失敗を意味しません。重複処理や追加課金を避けるため、再アップロード前にタスク一覧を確認してください。汎用的な Idempotency-Key による重複排除は提供していません。

制限とエラー

レート制限、課金、エラー処理

キーごとの毎秒の初期制限は認識 2 回、登録・書き込み 10 回、読み取り 20 回です。配備設定で変更できます。429 では Retry-After に従ってください。通常の成功 JSON 応答で X-RateLimit-Limit と X-RateLimit-Remaining を確認できます。

画像サイズの初期上限は 15 MiB で変更可能です。JPEG、PNG、WebP に対応します。登録と認識は猫の特徴抽出に課金されます。料金と付与枠はコンソールで確認してください。エラーの detail は文字列、オブジェクト、検証配列の場合があります。HTTP 状態と X-Request-Id を保存してください。

HTTP	エラーコード / detail	説明
401	`invalid_api_key`	キーの形式・シークレットが無効、またはキーが存在しません
401	`expired_api_key`	キーの有効期限が切れています
403	`api_key_disabled / api_key_revoked`	キーが無効化または取り消されています
403	`project_mismatch`	別のプロジェクトのキーです
403	`scope_denied`	必要な権限がありません
403	`ip_not_allowed`	送信元IPが許可されていません
404	`Not found`	プロジェクト・個体・画像・タスクが見つかりません
409	`Conflict`	現在のタスク状態では実行できません
413	`Image is too large`	画像が設定されたサイズ制限を超えています
415	`Unsupported media type`	JPEG、PNG、WebPのみ対応しています
422	`Validation error`	必須項目・型・範囲を確認してください
429	`rate_limit_exceeded`	同時実行数を減らしRetry-Afterに従ってください
503	`Recognition task failed`	推論に失敗しました。再試行前にタスク状態を確認してください

API リファレンス / v1

猫を識別

POST/v1/projects/{project_id}/search

必要な権限： recognition:write。プロジェクト所有者のログイントークンも利用できます。パスのプレースホルダーを実際の ID に置き換えてください。

multipart/form-data を使用し、必須のファイル項目 image に画像を設定します。一回につき JPEG、PNG、WebP のいずれか一枚を送信し、Content-Type と boundary はクライアントに生成させてください。

検索パラメータと結果

top_k は 1〜100 の整数で、初期値は 5（変更可能）です。 threshold は −1〜1 の任意の類似度しきい値です。省略時はモデルの既定値を使います。

matches は類似度順の候補一覧です。 unknown=true はしきい値を満たす信頼できる個体がないことを示します。 candidates 内の score は検出スコアで、個体の類似度ではありません。顔の検出は身元の識別を意味しません。

{
  "cat_count": 1,
  "route": "face",
  "face_detected": true,
  "unknown": true,
  "matches": [],
  "candidates": [
    {
      "index": 0,
      "score": 0.95,
      "route": "face",
      "face_detected": true,
      "unknown": true,
      "matches": []
    }
  ],
  "task_id": "<task_id>"
}

応答構造の例です。実際の認識結果ではありません。

cURL / Postman

curl --request POST '{{base_url}}/v1/projects/{project_id}/search?top_k=5' \
  --header 'Authorization: Bearer {{api_key}}' \
  --form 'image=@cat.jpg;type=image/jpeg'

Python の例を見る

import os
import requests

api_key = os.environ["MEOWID_API_KEY"]
base_url = os.environ["MEOWID_API_BASE"].rstrip("/")
# {project_id}、{cat_id} などを実際の ID に置き換えてください。
with open("cat.jpg", "rb") as image:
    response = requests.post(
        base_url + "/v1/projects/{project_id}/search?top_k=5",
        headers={"Authorization": f"Bearer {api_key}"},
        files={"image": ("cat.jpg", image, "image/jpeg")},
        timeout=120,
    )
response.raise_for_status()
print(response.content)

API リファレンス / v1

個体を作成

POST/v1/projects/{project_id}/cats

必要な権限： cats:write。プロジェクト所有者のログイントークンも利用できます。パスのプレースホルダーを実際の ID に置き換えてください。

name は 1〜100 文字で、作成時に必須です。 metadata は JSON オブジェクトです。 active の既定値は true です。変更する項目だけを送ってください。

cURL / Postman

curl --request POST '{{base_url}}/v1/projects/{project_id}/cats' \
  --header 'Authorization: Bearer {{api_key}}' \
  --header 'Content-Type: application/json' \
  --data '{"name":"Mimi","metadata":{},"active":true}'

Python の例を見る

import os
import json
import requests

api_key = os.environ["MEOWID_API_KEY"]
base_url = os.environ["MEOWID_API_BASE"].rstrip("/")
# {project_id}、{cat_id} などを実際の ID に置き換えてください。
response = requests.post(
    base_url + "/v1/projects/{project_id}/cats",
    headers={"Authorization": f"Bearer {api_key}"},
    json=json.loads("{\"name\":\"Mimi\",\"metadata\":{},\"active\":true}"),
    timeout=120,
)
response.raise_for_status()
print(response.content)

API リファレンス / v1

個体一覧

GET/v1/projects/{project_id}/cats

必要な権限： cats:read。プロジェクト所有者のログイントークンも利用できます。パスのプレースホルダーを実際の ID に置き換えてください。

cURL / Postman

curl --request GET '{{base_url}}/v1/projects/{project_id}/cats' \
  --header 'Authorization: Bearer {{api_key}}'

Python の例を見る

import os
import requests

api_key = os.environ["MEOWID_API_KEY"]
base_url = os.environ["MEOWID_API_BASE"].rstrip("/")
# {project_id}、{cat_id} などを実際の ID に置き換えてください。
response = requests.get(
    base_url + "/v1/projects/{project_id}/cats",
    headers={"Authorization": f"Bearer {api_key}"},
    timeout=120,
)
response.raise_for_status()
print(response.content)

API リファレンス / v1

個体を更新

PATCH/v1/projects/{project_id}/cats/{cat_id}

必要な権限： cats:write。プロジェクト所有者のログイントークンも利用できます。パスのプレースホルダーを実際の ID に置き換えてください。

name は 1〜100 文字で、作成時に必須です。 metadata は JSON オブジェクトです。 active の既定値は true です。変更する項目だけを送ってください。

cURL / Postman

curl --request PATCH '{{base_url}}/v1/projects/{project_id}/cats/{cat_id}' \
  --header 'Authorization: Bearer {{api_key}}' \
  --header 'Content-Type: application/json' \
  --data '{"name":"Mimi","active":true}'

Python の例を見る

import os
import json
import requests

api_key = os.environ["MEOWID_API_KEY"]
base_url = os.environ["MEOWID_API_BASE"].rstrip("/")
# {project_id}、{cat_id} などを実際の ID に置き換えてください。
response = requests.patch(
    base_url + "/v1/projects/{project_id}/cats/{cat_id}",
    headers={"Authorization": f"Bearer {api_key}"},
    json=json.loads("{\"name\":\"Mimi\",\"active\":true}"),
    timeout=120,
)
response.raise_for_status()
print(response.content)

API リファレンス / v1

個体を削除

DELETE/v1/projects/{project_id}/cats/{cat_id}

必要な権限： cats:write。プロジェクト所有者のログイントークンも利用できます。パスのプレースホルダーを実際の ID に置き換えてください。

個体を削除すると画像とベクトルも削除されます。画像を削除すると対応するベクトルが削除されます。個体削除の成功応答は本文なしの 204 です。

cURL / Postman

curl --request DELETE '{{base_url}}/v1/projects/{project_id}/cats/{cat_id}' \
  --header 'Authorization: Bearer {{api_key}}'

Python の例を見る

import os
import requests

api_key = os.environ["MEOWID_API_KEY"]
base_url = os.environ["MEOWID_API_BASE"].rstrip("/")
# {project_id}、{cat_id} などを実際の ID に置き換えてください。
response = requests.delete(
    base_url + "/v1/projects/{project_id}/cats/{cat_id}",
    headers={"Authorization": f"Bearer {api_key}"},
    timeout=120,
)
response.raise_for_status()
print(response.content)

API リファレンス / v1

画像を登録

POST/v1/projects/{project_id}/cats/{cat_id}/images

必要な権限： cats:write。プロジェクト所有者のログイントークンも利用できます。パスのプレースホルダーを実際の ID に置き換えてください。

202 queued と task_id を返します。タスク一覧で登録状況を確認できます。

cURL / Postman

curl --request POST '{{base_url}}/v1/projects/{project_id}/cats/{cat_id}/images' \
  --header 'Authorization: Bearer {{api_key}}' \
  --form 'image=@cat.jpg;type=image/jpeg'

Python の例を見る

import os
import requests

api_key = os.environ["MEOWID_API_KEY"]
base_url = os.environ["MEOWID_API_BASE"].rstrip("/")
# {project_id}、{cat_id} などを実際の ID に置き換えてください。
with open("cat.jpg", "rb") as image:
    response = requests.post(
        base_url + "/v1/projects/{project_id}/cats/{cat_id}/images",
        headers={"Authorization": f"Bearer {api_key}"},
        files={"image": ("cat.jpg", image, "image/jpeg")},
        timeout=120,
    )
response.raise_for_status()
print(response.content)

API リファレンス / v1

画像一覧

GET/v1/projects/{project_id}/cats/{cat_id}/images

必要な権限： cats:read。プロジェクト所有者のログイントークンも利用できます。パスのプレースホルダーを実際の ID に置き換えてください。

cURL / Postman

curl --request GET '{{base_url}}/v1/projects/{project_id}/cats/{cat_id}/images' \
  --header 'Authorization: Bearer {{api_key}}'

Python の例を見る

import os
import requests

api_key = os.environ["MEOWID_API_KEY"]
base_url = os.environ["MEOWID_API_BASE"].rstrip("/")
# {project_id}、{cat_id} などを実際の ID に置き換えてください。
response = requests.get(
    base_url + "/v1/projects/{project_id}/cats/{cat_id}/images",
    headers={"Authorization": f"Bearer {api_key}"},
    timeout=120,
)
response.raise_for_status()
print(response.content)

API リファレンス / v1

画像を取得

GET/v1/projects/{project_id}/cats/{cat_id}/images/{image_id}/content

必要な権限： cats:read。プロジェクト所有者のログイントークンも利用できます。パスのプレースホルダーを実際の ID に置き換えてください。

成功応答は画像のバイナリデータで、JSON ではありません。

cURL / Postman

curl --request GET '{{base_url}}/v1/projects/{project_id}/cats/{cat_id}/images/{image_id}/content' \
  --header 'Authorization: Bearer {{api_key}}'

Python の例を見る

import os
import requests

api_key = os.environ["MEOWID_API_KEY"]
base_url = os.environ["MEOWID_API_BASE"].rstrip("/")
# {project_id}、{cat_id} などを実際の ID に置き換えてください。
response = requests.get(
    base_url + "/v1/projects/{project_id}/cats/{cat_id}/images/{image_id}/content",
    headers={"Authorization": f"Bearer {api_key}"},
    timeout=120,
)
response.raise_for_status()
print(response.content)

API リファレンス / v1

メイン画像を設定

PATCH/v1/projects/{project_id}/cats/{cat_id}/images/{image_id}/primary

必要な権限： cats:write。プロジェクト所有者のログイントークンも利用できます。パスのプレースホルダーを実際の ID に置き換えてください。

cURL / Postman

curl --request PATCH '{{base_url}}/v1/projects/{project_id}/cats/{cat_id}/images/{image_id}/primary' \
  --header 'Authorization: Bearer {{api_key}}'

Python の例を見る

import os
import requests

api_key = os.environ["MEOWID_API_KEY"]
base_url = os.environ["MEOWID_API_BASE"].rstrip("/")
# {project_id}、{cat_id} などを実際の ID に置き換えてください。
response = requests.patch(
    base_url + "/v1/projects/{project_id}/cats/{cat_id}/images/{image_id}/primary",
    headers={"Authorization": f"Bearer {api_key}"},
    timeout=120,
)
response.raise_for_status()
print(response.content)

API リファレンス / v1

画像を削除

DELETE/v1/projects/{project_id}/cats/{cat_id}/images/{image_id}

必要な権限： cats:write。プロジェクト所有者のログイントークンも利用できます。パスのプレースホルダーを実際の ID に置き換えてください。

cURL / Postman

curl --request DELETE '{{base_url}}/v1/projects/{project_id}/cats/{cat_id}/images/{image_id}' \
  --header 'Authorization: Bearer {{api_key}}'

Python の例を見る

import os
import requests

api_key = os.environ["MEOWID_API_KEY"]
base_url = os.environ["MEOWID_API_BASE"].rstrip("/")
# {project_id}、{cat_id} などを実際の ID に置き換えてください。
response = requests.delete(
    base_url + "/v1/projects/{project_id}/cats/{cat_id}/images/{image_id}",
    headers={"Authorization": f"Bearer {api_key}"},
    timeout=120,
)
response.raise_for_status()
print(response.content)

API リファレンス / v1

タスク一覧

GET/v1/projects/{project_id}/tasks

必要な権限： tasks:read。プロジェクト所有者のログイントークンも利用できます。パスのプレースホルダーを実際の ID に置き換えてください。

limit は 1〜200、初期値は 100 です。 offset は 0 以上で、初期値は 0 です。応答配列にはタスク状態と result が含まれます。

cURL / Postman

curl --request GET '{{base_url}}/v1/projects/{project_id}/tasks?limit=10&offset=0' \
  --header 'Authorization: Bearer {{api_key}}'

Python の例を見る

import os
import requests

api_key = os.environ["MEOWID_API_KEY"]
base_url = os.environ["MEOWID_API_BASE"].rstrip("/")
# {project_id}、{cat_id} などを実際の ID に置き換えてください。
response = requests.get(
    base_url + "/v1/projects/{project_id}/tasks?limit=10&offset=0",
    headers={"Authorization": f"Bearer {api_key}"},
    timeout=120,
)
response.raise_for_status()
print(response.content)

API リファレンス / v1

タスク概要

GET/v1/projects/{project_id}/tasks/summary

必要な権限： tasks:read。プロジェクト所有者のログイントークンも利用できます。パスのプレースホルダーを実際の ID に置き換えてください。

cURL / Postman

curl --request GET '{{base_url}}/v1/projects/{project_id}/tasks/summary' \
  --header 'Authorization: Bearer {{api_key}}'

Python の例を見る

import os
import requests

api_key = os.environ["MEOWID_API_KEY"]
base_url = os.environ["MEOWID_API_BASE"].rstrip("/")
# {project_id}、{cat_id} などを実際の ID に置き換えてください。
response = requests.get(
    base_url + "/v1/projects/{project_id}/tasks/summary",
    headers={"Authorization": f"Bearer {api_key}"},
    timeout=120,
)
response.raise_for_status()
print(response.content)

API リファレンス / v1

検索画像を取得

GET/v1/projects/{project_id}/tasks/{task_id}/query

必要な権限： tasks:read。プロジェクト所有者のログイントークンも利用できます。パスのプレースホルダーを実際の ID に置き換えてください。

成功応答は画像のバイナリデータで、JSON ではありません。

cURL / Postman

curl --request GET '{{base_url}}/v1/projects/{project_id}/tasks/{task_id}/query' \
  --header 'Authorization: Bearer {{api_key}}'

Python の例を見る

import os
import requests

api_key = os.environ["MEOWID_API_KEY"]
base_url = os.environ["MEOWID_API_BASE"].rstrip("/")
# {project_id}、{cat_id} などを実際の ID に置き換えてください。
response = requests.get(
    base_url + "/v1/projects/{project_id}/tasks/{task_id}/query",
    headers={"Authorization": f"Bearer {api_key}"},
    timeout=120,
)
response.raise_for_status()
print(response.content)

API リファレンス / v1

候補画像を取得

GET/v1/projects/{project_id}/tasks/{task_id}/candidates/{candidate_index}

必要な権限： tasks:read。プロジェクト所有者のログイントークンも利用できます。パスのプレースホルダーを実際の ID に置き換えてください。

成功応答は画像のバイナリデータで、JSON ではありません。

cURL / Postman

curl --request GET '{{base_url}}/v1/projects/{project_id}/tasks/{task_id}/candidates/{candidate_index}' \
  --header 'Authorization: Bearer {{api_key}}'

Python の例を見る

import os
import requests

api_key = os.environ["MEOWID_API_KEY"]
base_url = os.environ["MEOWID_API_BASE"].rstrip("/")
# {project_id}、{cat_id} などを実際の ID に置き換えてください。
response = requests.get(
    base_url + "/v1/projects/{project_id}/tasks/{task_id}/candidates/{candidate_index}",
    headers={"Authorization": f"Bearer {api_key}"},
    timeout=120,
)
response.raise_for_status()
print(response.content)

API リファレンス / v1

登録候補を選択

POST/v1/projects/{project_id}/tasks/{task_id}/selection

必要な権限： cats:write。プロジェクト所有者のログイントークンも利用できます。パスのプレースホルダーを実際の ID に置き換えてください。

waiting_user の登録タスクにのみ利用できます。他の状態は 409 を返します。candidate_index は 0 以上の整数です。

cURL / Postman

curl --request POST '{{base_url}}/v1/projects/{project_id}/tasks/{task_id}/selection' \
  --header 'Authorization: Bearer {{api_key}}' \
  --header 'Content-Type: application/json' \
  --data '{"candidate_index":0}'

Python の例を見る

import os
import json
import requests

api_key = os.environ["MEOWID_API_KEY"]
base_url = os.environ["MEOWID_API_BASE"].rstrip("/")
# {project_id}、{cat_id} などを実際の ID に置き換えてください。
response = requests.post(
    base_url + "/v1/projects/{project_id}/tasks/{task_id}/selection",
    headers={"Authorization": f"Bearer {api_key}"},
    json=json.loads("{\"candidate_index\":0}"),
    timeout=120,
)
response.raise_for_status()
print(response.content)

API リファレンス / v1

選択待ちの登録を中止

POST/v1/projects/{project_id}/tasks/{task_id}/cancel

必要な権限： cats:write。プロジェクト所有者のログイントークンも利用できます。パスのプレースホルダーを実際の ID に置き換えてください。

waiting_user の登録タスクにのみ利用できます。他の状態は 409 を返します。candidate_index は 0 以上の整数です。

cURL / Postman

curl --request POST '{{base_url}}/v1/projects/{project_id}/tasks/{task_id}/cancel' \
  --header 'Authorization: Bearer {{api_key}}'

Python の例を見る

import os
import requests

api_key = os.environ["MEOWID_API_KEY"]
base_url = os.environ["MEOWID_API_BASE"].rstrip("/")
# {project_id}、{cat_id} などを実際の ID に置き換えてください。
response = requests.post(
    base_url + "/v1/projects/{project_id}/tasks/{task_id}/cancel",
    headers={"Authorization": f"Bearer {api_key}"},
    timeout=120,
)
response.raise_for_status()
print(response.content)

API リファレンス / v1

失敗タスクを再試行

POST/v1/projects/{project_id}/tasks/{task_id}/retry

必要な権限： cats:write / recognition:write。プロジェクト所有者のログイントークンも利用できます。パスのプレースホルダーを実際の ID に置き換えてください。

元データが残っている failed タスクのみ再試行でき、成功時は 202 を返します。

cURL / Postman

curl --request POST '{{base_url}}/v1/projects/{project_id}/tasks/{task_id}/retry' \
  --header 'Authorization: Bearer {{api_key}}'

Python の例を見る

import os
import requests

api_key = os.environ["MEOWID_API_KEY"]
base_url = os.environ["MEOWID_API_BASE"].rstrip("/")
# {project_id}、{cat_id} などを実際の ID に置き換えてください。
response = requests.post(
    base_url + "/v1/projects/{project_id}/tasks/{task_id}/retry",
    headers={"Authorization": f"Bearer {api_key}"},
    timeout=120,
)
response.raise_for_status()
print(response.content)

パス、リクエスト本文、権限は既存プラットフォームのドキュメントから同期しています。実装例はプレースホルダーのみで、有効な秘密キーは含みません。

あなたのアプリに、 猫を見分ける力を。

最初のリクエストの前に

プロジェクトごとの認証情報

登録は非同期、検索は結果を待機

レート制限、課金、エラー処理

猫を識別

検索パラメータと結果

cURL / Postman

個体を作成

cURL / Postman

個体一覧

cURL / Postman

個体を更新

cURL / Postman

個体を削除

cURL / Postman

画像を登録

cURL / Postman

画像一覧

cURL / Postman

画像を取得

cURL / Postman

メイン画像を設定

cURL / Postman

画像を削除

cURL / Postman

タスク一覧

cURL / Postman

タスク概要

cURL / Postman

検索画像を取得

cURL / Postman

候補画像を取得

cURL / Postman

登録候補を選択

cURL / Postman

選択待ちの登録を中止

cURL / Postman

失敗タスクを再試行

cURL / Postman

あなたのアプリに、
猫を見分ける力を。