РАЗРАБОТЧИКАМ / OPENAPI v1

Научите приложение
узнавать кошек.

Руководство по API Maopu

От первого регистрационного фото до поиска личности. Используйте HTTP для реестров кошек, управления задачами и получения кандидатов.

Открытая документация · Вход не нужен

Перед первым запросом

Войдите в консоль, создайте проект и скопируйте полный UUID.
Создайте ключ API проекта, задайте права и сохраните секрет: он показывается только один раз.
Создайте карточку кошки, сохраните полученный id и загрузите фото.
Проверьте список задач. После завершения регистрации загрузите поисковое фото и получите ранжированные совпадения.

В примерах {{base_url}}— HTTPS-адрес вашего API, а {{api_key}} — ключ проекта. Адрес берётся из настроек развёртывания или у поставщика. Этот сайт содержит документацию, а не обслуживает запросы /v1.

Примеры cURL используют переносы Bash. В Windows импортируйте их в Postman через Import → Raw text, задайте base_url и api_key и снова выберите файлы. Python запускайте на сервере с установленным requests и настроенными переменными окружения.

АВТОРИЗАЦИЯ

Доступ в пределах проекта

Рабочие методы принимают Authorization: Bearer mk_live_… или токен входа владельца проекта. Ключ привязан к проекту и предоставляет доступ в рамках своих прав.

Право доступа	Разрешённые операции
`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 каждые несколько секунд и находите task_id по id. Отдельного метода деталей GET /tasks/ {task_id} нет. Задачи отсортированы от новых к старым. Используйте offset и удаляйте дубликаты по ID.

При нескольких кошках регистрация может перейти в waiting_user. Просмотрите кандидатов и отправьте candidate_index через selection либо отмените через cancel. Повтор доступен только для неудачных задач.

Тайм-аут не означает провал задачи. Перед повторной загрузкой проверьте задачи, чтобы избежать дублирования и расходов. Общей дедупликации 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	Код ошибки / детали	Описание
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. Также принимается токен владельца. Замените параметры пути реальными идентификаторами.

Используйте 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 '[email protected];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. Также принимается токен владельца. Замените параметры пути реальными идентификаторами.

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. Также принимается токен владельца. Замените параметры пути реальными идентификаторами.

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}

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}

Удаление карточки удаляет её изображения и векторы; удаление изображения — его векторы. Удаление карточки возвращает 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

Возвращает 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 '[email protected];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

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

Успешный ответ содержит двоичные данные изображения, не 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

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}

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. Также принимается токен владельца. Замените параметры пути реальными идентификаторами.

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

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

Успешный ответ содержит двоичные данные изображения, не 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}

Успешный ответ содержит двоичные данные изображения, не 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

Только для регистрации в waiting_user. Другие состояния возвращают 409. candidate_index — неотрицательное целое.

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

Только для регистрации в waiting_user. Другие состояния возвращают 409. candidate_index — неотрицательное целое.

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. Также принимается токен владельца. Замените параметры пути реальными идентификаторами.

Повторяются только неудачные задачи с сохранённым источником. При успехе возвращается 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

Научите приложение
узнавать кошек.