> API поиска по лицу для обратного поиска по лицу в интернете. Отправьте одно фото — получите публичные профили, где встречается это лицо, с оценкой достоверности для каждого совпадения. Один кредит за поиск, без подписки и без минимального платежа в месяц. **API ПОИСКА ПО ЛИЦУ** # ПОИСК ПО ЛИЦУ, ПРЯМО ИЗ ВАШЕГО КОДА. **API поиска по лицу** по открытому интернету. Отправьте одно фото лица — получите страницы и профили, где оно встречается, с оценкой достоверности и ссылкой для каждого совпадения. Один кредит за поиск, цена в долларах, без подписки и без минимального платежа в месяц. Без звонка от отдела продаж · Без минимального платежа в месяц · Кредиты не сгорают Также доступен на [RapidAPI](https://rapidapi.com/muratcankuruoffical/api/trace-reverse-face-search-api) · [спецификация OpenAPI](https://traceaifacescan.app/openapi.json) · [примеры кода на GitHub](https://github.com/muratcankuruoffical/reverse-face-search-api) · [Hugging Face Space](https://huggingface.co/spaces/muratcankuru/reverse-face-search) · [Apify Actor](https://apify.com/muratcankuru/reverse-face-search) - Результат примерно за минуту - Один кредит за поиск - REST + JSON, ничего устанавливать не нужно - Собственный движок, не реселлер **ЧТО ДЕЛАЕТ API** ## ОДНО ФОТО НА ВХОДЕ. ВСЕ ПУБЛИЧНЫЕ СОВПАДЕНИЯ НА ВЫХОДЕ. Тот же движок, что работает в панели, с теми же результатами. API — это не урезанная версия. **ПОИСК ПО ЛИЦУ** ### Совпадение по лицу, а не по файлу. Обычный поиск по картинке находит копии того же изображения. Здесь сравнивается лицо, поэтому другое фото того же человека — в другой одежде, в другом году — всё равно даёт совпадение. **ОЦЕНКА ДОСТОВЕРНОСТИ** ### У каждого совпадения есть число. У каждого результата есть оценка сходства от 50 до 100 и диапазон: возможное совпадение от 70, сильное от 80, почти точное от 90. Ничего не возвращается как вердикт. **АККАУНТЫ В СОЦСЕТЯХ** ### Аккаунт, а не только страница. Если ссылка принадлежит аккаунту, имя пользователя и платформа возвращаются отдельными полями — разбирать URL на своей стороне не нужно. **СОБСТВЕННЫЙ ДВИЖОК** ### Не реселлер. Trace работает на собственном сервисе поиска по лицу. Именно поэтому поиск стоит центы, а не доллары, и поэтому нам не нужно ограничивать количество ваших запросов. **БЫСТРЫЙ СТАРТ** ## ТРИ ЗАПРОСА ОТ НАЧАЛА ДО КОНЦА. Авторизация — это один заголовок. Устанавливать SDK и выполнять handshake не нужно. ### Запустите сканирование Multipart-запрос, имя поля `image`. JPEG, PNG или WebP, до 8 МБ, не менее 200 пикселей по короткой стороне. `Idempotency-Key` необязателен и делает повтор запроса безопасным. ```bash curl -X POST https://traceaifacescan.app/api/v1/scans \ -H "Authorization: Bearer trk_live_..." \ -H "Idempotency-Key: $(uuidgen)" \ -F image=@face.jpg ``` **202 ACCEPTED** ```json { "id": "01m0jr1j5cbhwqsnt5qjx3zyd8", "status": "queued", "progress": 0, "locked": false, "match_count": 0, "credits_remaining": 9 } ``` ### Опрашивайте до завершения Поиск занимает примерно 25–45 секунд. Опрашивайте каждую секунду-две, пока `status` не станет `done` или `failed`. ```bash curl https://traceaifacescan.app/api/v1/scans/01m0jr1j5cbhwqsnt5qjx3zyd8 \ -H "Authorization: Bearer trk_live_..." ``` **200 OK** ```json { "status": "done", "progress": 100, "locked": false, "match_count": 2, "matches": [ { "score": 88, "tier": "strong", "platform": "x", "handle": "@alexrivers88", "url": "https://x.com/alexrivers88", "preview_url": ".../scans/01m0.../previews/0" } ] } ``` ### Потратьте кредит Сканирование, созданное без доступных кредитов, возвращается с `locked: true` и без совпадений — поиск не выполнялся. Раскрытие результатов — отдельный вызов намеренно: скрипт, перебирающий список сканирований, не должен случайно опустошить ваш баланс. ```bash curl -X POST \ https://traceaifacescan.app/api/v1/scans/01m0.../reveal \ -H "Authorization: Bearer trk_live_..." ``` **ЭНДПОИНТЫ** ## ВСЯ ПОВЕРХНОСТЬ API. Семь эндпоинтов. Машиночитаемое описание находится в [openapi.json](https://traceaifacescan.app/openapi.json), а полная документация с телами ответов — в [docs](https://traceaifacescan.app/docs). - **POST** — `/v1/scans` — Запустить сканирование по фото. - **GET** — `/v1/scans/{id}` — Статус, прогресс и совпадения. - **GET** — `/v1/scans` — Ваши сканирования с пагинацией. - **POST** — `/v1/scans/{id}/reveal` — Потратить кредит и выполнить настоящий поиск. - **GET** — `/v1/scans/{id}/previews/{n}` — Миниатюра лица одного совпадения. - **DELETE** — `/v1/scans/{id}` — Удалить сканирование, его изображение и превью. - **GET** — `/v1/account` — Ваш баланс кредитов. **ОШИБКИ И ОГРАНИЧЕНИЯ** ## ПРЕДСКАЗУЕМЫЕ ОШИБКИ. Ошибки возвращаются как `application/problem+json` со стабильной строкой `code`. Ориентируйтесь на код, а не на текст сообщения. - **402** — `insufficient_credits` — Кредиты закончились. Поиск не выполнялся, списание не производилось. - **404** — `no_face_detected` — На изображении нет лица. Нужно другое фото, а не повтор запроса. - **429** — `rate_limited` — Только после повторных неудачных попыток авторизации. `Retry-After` указывает, когда повторить. - **401** — `unauthorized` — Ключ отсутствует, неверен или отозван. - **503** — `provider_unavailable` — Проблема на нашей стороне. Кредит, зарезервированный для неудачного поиска, всегда возвращается. ### Ограничения - **Нет ограничения частоты запросов.** Чтения не учитываются, потолка в минуту нет. - Ваше реальное ограничение — **баланс кредитов**: сканирование стоит кредит, чтение ничего не стоит. - Изображения до **8 МБ**, не менее **200 пикселей** по короткой стороне. - Сканирования и их изображения удаляются через **30 дней**. `DELETE` удаляет их немедленно. **ЦЕНЫ** ## ОДИН КРЕДИТ — ОДИН ПОИСК. Те же кредиты, что использует панель, из того же баланса. Без подписки, без минимального платежа в месяц, и они не сгорают. Пакет на 100 кредитов — тот, вокруг которого построен API. Оплата картой, Telegram Stars или криптовалютой — см. [пакеты кредитов](https://traceaifacescan.app/ru/#pricing). Нужен объём больше самого крупного пакета? [Напишите нам](https://docs.google.com/forms/d/e/1FAIpQLSdVeyYm3BLWkEnmHToK5_JQynOHCctKTxMkBJp3PJf-pmaLYQ/viewform). **ЧЕСТНЫЕ ОГРАНИЧЕНИЯ** ## ЧЕГО ЭТОТ API НЕ ДЕЛАЕТ. **Это не сервис идентификации.** Совпадение — это оценка сходства между двумя изображениями, а не утверждение о том, кто этот человек. В ответе нет ни имени, ни адреса, ни телефона, ни каких-либо записей — только публичные ссылки и число. **Пустой результат — не доказательство отсутствия.** Это означает, что ничего не нашлось в той части открытого интернета, которую мы можем охватить. Если у человека нет публичных фото, искать нечего, и никакой API этого не изменит. **Ничего, что скрыто за авторизацией, не затрагивается.** Каждый результат — это страница, которая уже была публичной. **Запрещено использовать для проверки биографии, найма, кредитования, страхования, слежки или правоохранительных целей**, а также против несовершеннолетних. Отправляйте только те фото, на поиск которых у вас есть право. Это прописано в [Условиях использования](https://traceaifacescan.app/ru/usloviya/), и мы следим за этим — ключ, использованный таким образом, отзывается. **ЧАСТЫЕ ВОПРОСЫ** ## ЧТО СНАЧАЛА СПРАШИВАЮТ РАЗРАБОТЧИКИ. ### Что такое API поиска по лицу? Это HTTP API, который принимает фотографию лица и возвращает другие места в открытом интернете, где встречается это же лицо. В отличие от поиска по картинке, который сравнивает файлы изображений, поиск по лицу сравнивает геометрию лица — поэтому находит того же человека на совершенно другом фото. Версия Trace — это REST API с ответами в формате JSON: один POST-запрос запускает сканирование, один GET-запрос читает совпадения. ### Сколько стоит поиск по лицу через API? Один кредит за поиск, кредиты продаются пакетами в долларах США — от $4 за пять кредитов до $50 за сто. Нет подписки, нет минимального платежа в месяц и нет срока действия. API тратит тот же баланс, что и панель. ### Есть ли бесплатный тариф или пробный период? Бесплатного поиска через API нет. Запрос от аккаунта без кредитов создаёт сканирование, но не выполняет поиск: он возвращается заблокированным, без совпадений. Панель показывает авторизованному посетителю статический пример результата, чтобы он увидел, как выглядит готовый случай, — а API намеренно никогда не возвращает такой пример: заглушка — это то, на чём можно построить скрипт. ### Как быстро выполняется поиск? От 25 до 45 секунд в среднем, иногда до 90. Именно поэтому API асинхронный: POST сразу возвращает 202 с идентификатором, а вы опрашиваете статус. Удержание открытого HTTP-запроса в течение минуты превратило бы закрытое соединение в отменённый поиск. ### Можно ли использовать ссылки на изображения вместо загрузки файла? Не в v1. Приём ссылки превратил бы API в SSRF-проксирование — мы бы обращались к произвольным адресам от имени вызывающего из своей сети. Если эта возможность появится, то с белым списком и запретом на приватные диапазоны адресов. ### Есть ли ограничение частоты запросов к API? Нет. Вызывайте так быстро, как позволяет ваш код — чтения не учитываются, и потолка в минуту нет. Единственное, что вас ограничивает, — баланс кредитов, потому что сканирование стоит кредит, а чтение ничего не стоит. Остаётся один защитный лимит, и действующий ключ его не замечает: повторные неудачные попытки авторизации с одного адреса замедляются, чтобы подбор ключей оставался дорогим. ### Законно ли использовать API поиска по лицу? Это полностью зависит от того, для чего и где вы его используете. Проверка того, что фото на вашей собственной платформе принадлежит тому, кто его использует, — это не то же самое, что создание базы данных лиц. Данные о лице — особая категория по GDPR и KVKK, и вы являетесь контролёром данных, которые отправляете нам. Прочитайте Условия использования: проверки биографии, наём, кредитование, страхование, слежка и правоохранительные цели — всё это недопустимо. ### Это API распознавания лиц или API поиска по картинке? Это API поиска по лицу — частный случай распознавания лиц. Он не сравнивает два предоставленных вами фото, не проверяет документ, удостоверяющий личность, и не возвращает сведения о том, кто этот человек. Он принимает одну фотографию и ищет в открытом интернете другие изображения того же лица, возвращая каждое совпадение как публичную ссылку с оценкой достоверности. Именно это отличает его от API поиска по картинке: поиск по картинке сравнивает файл изображения и находит копии той же картинки, а этот API сравнивает геометрию лица и находит то же лицо на другом фото. **API ПОИСКА ПО ЛИЦУ** ## НАЧНИТЕ С ОДНОГО ЗАПРОСА. Создайте ключ в панели — и первый curl-запрос сработает сразу.