API 레퍼런스
하나의 엔드포인트, 몇 가지 파라미터, 두 가지 인증 방식.
레퍼런스보다 먼저 마이그레이션 경로가 필요하다면
먼저 Clearbit 대체 가이드 또는 로고 API 구매 가이드를 읽어보세요.
ClearLogo 는 단일 HTTP 엔드포인트
GET /logo/{domain}만 노출하며, 도메인의 로고를 불투명한 테마 맞춤 배경(라이트는 흰색, 다크는 어두운 중립색) 위에 일정한 비율로 담아 PNG(또는 WebP/JPEG)로 돌려줍니다. 낮은 볼륨 테스트는 익명으로도 가능하며, 프로덕션 트래픽은 브라우저 키(클라이언트) 또는 서버 키(백엔드)를 사용합니다.
엔드포인트
GET https://api.clearlogo.dev/logo/:domain
:domain 은 스킴과 경로가 없는 순수 호스트명입니다. 예: github.com. 응답은 기본 image/png 입니다.
쿼리 파라미터
| 이름 | 타입 | 기본값 | 설명 |
|---|---|---|---|
size | number | 128 | 출력 이미지 한 변의 픽셀 크기입니다. 정사각형만 지원하며 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 헤더로 자동 협상됩니다. 현대 브라우저에서 <img> 로 불러오면 WebP가 자동 반환됩니다. |
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 힌트를 함께 보냅니다.
자주 묻는 질문
도메인 로고는 어떻게 가져오나요?
https://api.clearlogo.dev/logo/{domain} 에 GET 요청을 보내세요. {domain} 은 github.com 같은 순수 호스트명입니다. 낮은 볼륨 테스트는 로그인 없이 가능하며, 응답은 기본 PNG라 <img> 태그에서 바로 사용할 수 있습니다.
브라우저 키와 서버 키의 차이는 무엇인가요?
브라우저 키는 프론트엔드 코드와 <img> 태그에 그대로 노출해도 안전합니다. 키에 등록된 허용 도메인을 기준으로 요청이 검증됩니다. 서버 키는 Authorization: Bearer 헤더로 백엔드에서만 사용해야 하며, 절대 브라우저로 노출되어선 안 됩니다.
어떤 출력 포맷을 지원하나요?
png(기본), webp, jpeg 세 가지를 지원합니다. format 파라미터를 생략하면 요청의 Accept 헤더로 자동 협상되며, 현대 브라우저에서 <img> 로 불러올 때 WebP 가 자동 반환됩니다.
투명 배경이나 정사각형 크롭을 얻을 수 있나요?
출력은 항상 불투명한 정사각형 이미지입니다 — 투명 변형은 없습니다. 배경은 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)를 선택할 수 있으며, 요청한 파트가 없으면 전체 로고로 대체됩니다(별도 파트로 관리되는 로고의 경우 투명 이미지가 반환됩니다).