Справочник 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. |
frame | fill, original | fill | fill заполняет канвас (за вычетом отступа) визуальным содержимым логотипа, отбрасывая исходные пустые поля. original сохраняет оригинальное кадрирование и пропорции иконки источника. |
padding | number | 10 | Отступ с каждой стороны от содержимого, в % от канваса (0–20, шаг 5). |
shape | square, circle | square | square — стандартное кадрирование. circle вписывает логотип во вписанную окружность, чтобы он не обрезался в круглом аватаре — выходное изображение по-прежнему квадратное, без маски прозрачности. |
part | full, logo, text | full | Выбирает, какую часть логотипа вернуть — full (весь логотип), logo (иконка/знак) или text (словесный знак) — для доменов, чей логотип разделён на части. Если запрошенная часть недоступна, возвращается полный логотип (или прозрачное изображение для логотипов, управляемых как отдельные части). Части могут быть растровыми (PNG) и отображаются в своих реальных цветах. |
format | png | webp | jpeg | png | Формат вывода. Автоматически согласуется через заголовок Accept — современные браузеры автоматически получают WebP через <img>. |
theme | light | dark | light | Возвращает тёмный вариант, если доступен, иначе возвращается светлый. Также задаёт цвет непрозрачного фона: белый для light, тёмный нейтральный для dark. |
token | string | — | Браузерный ключ, используемый из клиентского кода. Origin или Referer должны совпадать с одним из разрешённых доменов на ключе. |
Типичный запрос с основными параметрами:
GET https://api.clearlogo.dev/logo/github.com?size=128&frame=fill&padding=10&shape=square
Запрос только иконки/знака разделённого логотипа с помощью part:
GET https://api.clearlogo.dev/logo/github.com?size=128&part=logo
Аутентификация
Анонимные запросы работают для низкого объёма тестирования. Для боевого трафика используйте браузерный ключ (клиент) или серверный ключ (бэкенд):
Браузер
<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>.
Какие ограничения скорости действуют?
Лимиты по ключам возвращаются в заголовках X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset. При превышении лимита API отвечает HTTP 429 с подсказкой Retry-After, указывающей, сколько секунд ждать перед повторной попыткой.
Можно ли получить прозрачный фон или квадратную обрезку?
Выходное изображение всегда непрозрачное и квадратное — прозрачного варианта не существует. Фон соответствует параметру theme: белый для light и тёмный нейтральный для dark. В пределах этого квадратного канваса вы управляете кадрированием: frame (fill, original) выбирает между заполнением канваса содержимым логотипа и сохранением оригинальных пропорций иконки источника; padding (0–20, шаг 5) задаёт отступ с каждой стороны; shape (square, circle) вписывает логотип во вписанную окружность при значении circle (изображение по-прежнему квадратное). Используйте size (допустимые значения: 16, 32, 48, 64, 96, 128, 192, 256, 512, 1024) для точного пиксельного размера. Для доменов с разделённым логотипом part (full, logo, text) выбирает весь логотип (full, по умолчанию), иконку/знак (logo) или словесный знак (text); если запрошенная часть недоступна, возвращается полный логотип (или прозрачное изображение для логотипов, управляемых как отдельные части).