Иконка приложения TraceTRACE
EN TR RU AR
Получить API-ключ

TRACE / API ПОИСКА ПО ЛИЦУ

API ПОИСКА ПО ЛИЦУ

ПОИСК ПО ЛИЦУ,
ПРЯМО ИЗ ВАШЕГО КОДА.

API поиска по лицу по открытому интернету. Отправьте одно фото лица — получите страницы и профили, где оно встречается, с оценкой достоверности и ссылкой для каждого совпадения. Один кредит за поиск, цена в долларах, без подписки и без минимального платежа в месяц.

Получить API-ключ Читать документацию

Без звонка от отдела продаж · Без минимального платежа в месяц · Кредиты не сгорают

Также доступен на RapidAPI · спецификация OpenAPI · примеры кода на GitHub · Hugging Face Space · Apify Actor

  • Результат примерно за минуту
  • Один кредит за поиск
  • REST + JSON, ничего устанавливать не нужно
  • Собственный движок, не реселлер
curl -X POST https://traceaifacescan.app/api/v1/scans \
  -H "Authorization: Bearer trk_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -F image=@face.jpg
{
  "id": "01m0jr1j5cbhwqsnt5qjx3zyd8",
  "status": "queued",
  "progress": 0,
  "locked": false,
  "match_count": 0,
  "credits_remaining": 9
}
ЧТО ДЕЛАЕТ API

ОДНО ФОТО НА ВХОДЕ. ВСЕ ПУБЛИЧНЫЕ СОВПАДЕНИЯ НА ВЫХОДЕ.

Тот же движок, что работает в панели, с теми же результатами. API — это не урезанная версия.

ПОИСК ПО ЛИЦУ

Совпадение по лицу, а не по файлу.

Обычный поиск по картинке находит копии того же изображения. Здесь сравнивается лицо, поэтому другое фото того же человека — в другой одежде, в другом году — всё равно даёт совпадение.

ОЦЕНКА ДОСТОВЕРНОСТИ

У каждого совпадения есть число.

У каждого результата есть оценка сходства от 50 до 100 и диапазон: возможное совпадение от 70, сильное от 80, почти точное от 90. Ничего не возвращается как вердикт.

АККАУНТЫ В СОЦСЕТЯХ

Аккаунт, а не только страница.

Если ссылка принадлежит аккаунту, имя пользователя и платформа возвращаются отдельными полями — разбирать URL на своей стороне не нужно.

СОБСТВЕННЫЙ ДВИЖОК

Не реселлер.

Trace работает на собственном сервисе поиска по лицу. Именно поэтому поиск стоит центы, а не доллары, и поэтому нам не нужно ограничивать количество ваших запросов.

БЫСТРЫЙ СТАРТ

ТРИ ЗАПРОСА ОТ НАЧАЛА ДО КОНЦА.

Авторизация — это один заголовок. Устанавливать SDK и выполнять handshake не нужно.

  1. 01

    Запустите сканирование

    Multipart-запрос, имя поля image. JPEG, PNG или WebP, до 8 МБ, не менее 200 пикселей по короткой стороне. Idempotency-Key необязателен и делает повтор запроса безопасным.

    curl -X POST https://traceaifacescan.app/api/v1/scans \
  -H "Authorization: Bearer trk_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -F image=@face.jpg
    202 ACCEPTED 
    {
  "id": "01m0jr1j5cbhwqsnt5qjx3zyd8",
  "status": "queued",
  "progress": 0,
  "locked": false,
  "match_count": 0,
  "credits_remaining": 9
}
  2. 02

    Опрашивайте до завершения

    Поиск занимает примерно 25–45 секунд. Опрашивайте каждую секунду-две, пока status не станет done или failed.

    curl https://traceaifacescan.app/api/v1/scans/01m0jr1j5cbhwqsnt5qjx3zyd8 \
  -H "Authorization: Bearer trk_live_..."
    200 OK 
    {
  "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"
    }
  ]
}
  3. 03

    Потратьте кредит

    Сканирование, созданное без доступных кредитов, возвращается с locked: true и без совпадений — поиск не выполнялся. Раскрытие результатов — отдельный вызов намеренно: скрипт, перебирающий список сканирований, не должен случайно опустошить ваш баланс.

    curl -X POST \
  https://traceaifacescan.app/api/v1/scans/01m0.../reveal \
  -H "Authorization: Bearer trk_live_..."
ЭНДПОИНТЫ

ВСЯ ПОВЕРХНОСТЬ API.

Семь эндпоинтов. Машиночитаемое описание находится в openapi.json, а полная документация с телами ответов — в 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. Ориентируйтесь на код, а не на текст сообщения.

  • 402insufficient_creditsКредиты закончились. Поиск не выполнялся, списание не производилось.
  • 404no_face_detectedНа изображении нет лица. Нужно другое фото, а не повтор запроса.
  • 429rate_limitedТолько после повторных неудачных попыток авторизации. Retry-After указывает, когда повторить.
  • 401unauthorizedКлюч отсутствует, неверен или отозван.
  • 503provider_unavailableПроблема на нашей стороне. Кредит, зарезервированный для неудачного поиска, всегда возвращается.

Ограничения

  • Нет ограничения частоты запросов. Чтения не учитываются, потолка в минуту нет.
  • Ваше реальное ограничение — баланс кредитов: сканирование стоит кредит, чтение ничего не стоит.
  • Изображения до 8 МБ, не менее 200 пикселей по короткой стороне.
  • Сканирования и их изображения удаляются через 30 дней. DELETE удаляет их немедленно.
ЦЕНЫ

ОДИН КРЕДИТ — ОДИН ПОИСК.

Те же кредиты, что использует панель, из того же баланса. Без подписки, без минимального платежа в месяц, и они не сгорают. Пакет на 100 кредитов — тот, вокруг которого построен API.

Оплата картой, Telegram Stars или криптовалютой — см. пакеты кредитов. Нужен объём больше самого крупного пакета? Напишите нам.

ЧЕСТНЫЕ ОГРАНИЧЕНИЯ

ЧЕГО ЭТОТ API НЕ ДЕЛАЕТ.

Это не сервис идентификации. Совпадение — это оценка сходства между двумя изображениями, а не утверждение о том, кто этот человек. В ответе нет ни имени, ни адреса, ни телефона, ни каких-либо записей — только публичные ссылки и число.

Пустой результат — не доказательство отсутствия. Это означает, что ничего не нашлось в той части открытого интернета, которую мы можем охватить. Если у человека нет публичных фото, искать нечего, и никакой API этого не изменит.

Ничего, что скрыто за авторизацией, не затрагивается. Каждый результат — это страница, которая уже была публичной.

Запрещено использовать для проверки биографии, найма, кредитования, страхования, слежки или правоохранительных целей, а также против несовершеннолетних. Отправляйте только те фото, на поиск которых у вас есть право. Это прописано в Условиях использования, и мы следим за этим — ключ, использованный таким образом, отзывается.

ЧАСТЫЕ ВОПРОСЫ

ЧТО СНАЧАЛА СПРАШИВАЮТ РАЗРАБОТЧИКИ.

Что такое 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-запрос сработает сразу.

Получить API-ключ Читать документацию