MeowID API 图文接入教程

准备一个 MeowID 账号，以及同一只猫的两张不同照片：一张用来登记，一张用来测试。首次建议使用只有一只猫、光线充足、猫脸清晰的照片。

整个流程是：创建项目 → 添加猫咪 → 上传参考照片 → 等待登记完成 → 识别测试 → 创建 Key → 调用 API。

官网用于了解产品和查看文档，控制台用于管理项目。真正的 API 请求发往 https://platform.meowid.net。

打开 MeowID 控制台。已有账号选择「登录」，新用户切换到「注册」，按照页面提示完成注册后登录。

登录后，打开左侧导航，在「项目」右侧点击 ＋。如果页面较窄，先点击左上角菜单按钮展开导航。

填写项目名称，例如「猫咪识别示例」，项目说明可以选填，然后点击「创建项目」。项目会隔离猫咪、图片和特征向量数据；后续登记与识别应使用同一个项目。

进入项目，点击 「复制项目 ID」，保存这个值。它对应后面接口地址里的 YOUR_PROJECT_ID。

在项目中点击「添加个体」，输入猫咪名称，例如 Mimi，保持「激活个体」开启，然后点击「添加个体」。关闭激活后，这只猫不会参与识别搜索。

当前控制台的新增弹窗填写名称与激活状态。如果还想保存性格、备注等信息，可以使用本文后面的 API 自动建档示例，将这些内容放入 metadata。

在「个体管理 → 个体列表」中，找到目标猫咪，点击该行的「照片库」，再点击 「添加注册图片」。

点击上传区域选择文件，或把照片拖入区域。确认照片属于这只猫后，点击「上传」。支持 JPEG、PNG 和 WebP，页面支持批量选择多张照片。

首次建议先用一张清晰的单猫照片跑通流程，再补充同一只猫的不同角度照片。不要把不同猫咪的照片放进同一个档案。

上传成功只表示图片已被接收。进入项目的 「任务队列」，找到刚刚提交的「注册图片」任务，等待状态变为 「已完成」。对应 API 状态值为 completed。

如果任务还在 queued 或 running，稍后再刷新；如果为 waiting_user，按控制台提示选择这张照片中的目标猫；如果为 failed，查看错误信息并处理后再重试。

完成登记后，再进行识别测试。 不要仅凭上传成功就判断档案已经可用于识别。

回到 「个体管理 → 识别测试」，上传同一只猫的另一张照片。示例将「返回数量」设为 3，「拒识阈值」设为 0.35，选好文件后点击「开始识别」。

3 表示最多返回三个候选猫；0.35 只是演示阈值。实际接入时，应使用你们自己的照片测试后确定阈值。用另一张照片测试，更有助于观察不同角度、光线和背景下的效果。

识别完成后查看结论和候选列表，也可以在「任务队列」中展开已有识别任务的「查看结果」。下图来自一个真实的历史任务，识别结论为「猫咪2」。

图中的 56.61% 是相似度的百分比展示，不是 56.61% 的识别正确率。 该历史任务使用 body 路由，页面标注「未检测到猫脸」；这是平台自动选择的全身特征检索路径，不要把它误读成猫脸检测成功。

在左侧导航进入「API Keys」。先确认上方选择的是刚才登记猫咪的项目，再点击「创建 API Key」。

填写一个方便识别用途的名称，例如 meowid-demo-server。选择 「自定义」（英文界面为 Custom），只保留 「执行识别 recognition:write」。

切换到「自定义」后，要检查并取消其他权限的勾选。 当前界面可能保留从「完整访问」带过来的选中状态，仅切换模式并不等于已经缩小权限。

按需要设置有效期与 IP 白名单，确认后点击「创建密钥」。完整 Key 只展示一次，请立即保存到服务端环境变量或密钥管理系统中。

API Key 只放服务端，不放在公开网页、前端代码、截图或 Git 仓库里。本文截图展示的是配置表单，不包含真实 Key。

把 YOUR_PROJECT_ID 和 YOUR_API_KEY 换成自己的值，准备一张查询照片 query.jpg。在包含该照片的目录中运行下面的命令。

macOS、Linux 或 WSL 终端：

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"

Windows PowerShell：把开头的 curl 改成 curl.exe，整条命令保持一行，其余内容相同。

示例使用 JPEG；如果换成 PNG，文件名和 MIME 类型也相应改为 query.png 与 image/png。WebP 使用 image/webp。不要手动设置整个 multipart 请求的 Content-Type，curl 会自动生成边界和正确的请求头。

识别接口会等待任务处理完成后返回结果。调用可能计费，执行前请查看控制台的额度与计费说明。

以下是省略其他字段的 格式示意，数值不是上面历史截图的原始响应：

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

读取时，先判断 unknown，再使用候选结果。

当 unknown=true 时，即使 matches 里仍有候选，也不要自动认定为某只已登记的猫。可以在业务中提示「暂未确认身份」，再人工确认或补充照片。

如果照片里有多只猫，需要遍历完整响应中的 candidates，分别读取每只猫的 unknown 和 matches。顶层的 unknown 与 matches 只对应第一只检测到的猫，不能代替整张照片的判断。

没有检测到猫时，cat_count 为 0，不要直接访问 matches[0]。以上简化 JSON 未展示 candidates 字段。

完成第一次接入后，可以把建档与参考照片登记也接入自己的服务端。此时在 Key 中增加 cats:write 和 tasks:read；如果还要执行识别，继续保留 recognition:write。

以上接口均使用 Authorization: Bearer YOUR_API_KEY。创建猫档案时，最简单的请求体是 {"name":"Mimi"}；需要记录性格和备注时，可以使用：

{
  "name": "Mimi",
  "metadata": {
    "personality": "亲人，喜欢晒太阳",
    "notes": "示例档案，可按业务需要扩展"
  },
  "active": true
}

personality 和 notes 是你自定义的元数据键，不是识别接口自动推断出的信息。识别后可用 cat_id 关联这些资料；不要假定识别响应会直接返回完整档案。

任务不在第一页时，继续增加 offset 查询，例如 offset=100、offset=200。找到目标任务后，如果仍为 queued 或 running，稍后再查；waiting_user 需要到控制台选择目标猫；failed 需要查看任务错误。

以后新增猫咪或补充参考照片，完成登记即可，不需要为每次新增档案重新训练模型。

这样就完成了首次接入。欢迎把 MeowID 接入你们的猫咪档案、救助管理或其他需要识别猫咪身份的应用。

完整接口与最新说明请查看 MeowID 开发者文档。