Справочник API

Один endpoint, несколько параметров, два способа аутентификации.

Нужен путь миграции перед справочником?

Начните с руководства замены Clearbit или руководства покупателя logo API.

ClearLogo предоставляет единственный HTTP-эндпоинт, GET /logo/{domain}, который возвращает PNG (или WebP/JPEG) логотипа домена с консистентным соотношением сторон и прозрачным фоном. Анонимное использование работает для тестов низкого объёма; для боевого трафика используется браузерный ключ (клиент) или серверный ключ (бэкенд).

Endpoint

GET https://api.clearlogo.dev/logo/:domain

:domain — это имя хоста без схемы и пути, например github.com. По умолчанию API возвращает image/png.

Параметры запроса

Название	Тип	По умолчанию	Примечания
`size`	number	`128`	Размер выходного изображения в px. Только квадратные. Допустимые значения: 16, 32, 48, 64, 96, 128, 192, 256, 512, 1024.
`content`	number	`80`	Занимаемое логотипом пространство внутри канваса (50–100, шаг 5).
`format`	`png \| webp \| jpeg`	`png`	Формат вывода. Автоматически согласуется через заголовок `Accept` — современные браузеры автоматически получают WebP через `<img>`.
`theme`	`light \| dark`	`light`	Возвращает тёмный вариант, если доступен, иначе возвращается светлый.
`token`	string	—	Браузерный ключ, используемый из клиентского кода. Origin или Referer должны совпадать с одним из разрешённых доменов на ключе.

Аутентификация

Анонимные запросы работают для низкого объёма тестирования. Для боевого трафика используйте браузерный ключ (клиент) или серверный ключ (бэкенд):

Браузер

<img
  src="https://api.clearlogo.dev/logo/example.com?token=YOUR_BROWSER_KEY"
  alt="" />

Сервер

curl \
  -H "Authorization: Bearer YOUR_SERVER_KEY" \
  "https://api.clearlogo.dev/logo/example.com"

Ограничения скорости

Лимиты по ключам возвращаются в заголовках X-RateLimit-*. При превышении API отвечает 429 и включает подсказку Retry-After.

Часто задаваемые вопросы

Как получить логотип для домена?

Отправьте GET-запрос на https://api.clearlogo.dev/logo/{domain}, где {domain} — имя хоста вроде github.com. Для тестов низкого объёма вход не требуется. Ответ по умолчанию — PNG, и он работает напрямую в тегах <img>.

В чём разница между браузерным и серверным ключом?

Браузерный ключ безопасен для размещения в коде фронтенда и тегах <img>; запросы проверяются против разрешённых доменов, которые вы настраиваете на ключе. Серверный ключ аутентифицируется через заголовок Authorization: Bearer с бэкенда и никогда не должен попадать в браузер.

Какие форматы вывода поддерживаются?

png (по умолчанию), webp и jpeg. Когда параметр format опущен, ClearLogo согласует содержимое через заголовок Accept запроса — современные браузеры автоматически получают WebP при загрузке API через тег <img>.