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 값을 사용할 수 있습니다.
`content`	number	`80`	캔버스 안에서 로고가 차지하는 비율입니다. 50–100 범위, 5 단위로 조정됩니다.
`format`	`png \| webp \| jpeg`	`png`	출력 포맷. 미지정 시 `Accept` 헤더로 자동 협상됩니다. 현대 브라우저에서 `<img>` 로 불러오면 WebP가 자동 반환됩니다.
`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 힌트를 함께 보냅니다.

자주 묻는 질문

도메인 로고는 어떻게 가져오나요?

https://api.clearlogo.dev/logo/{domain} 에 GET 요청을 보내세요. {domain} 은 github.com 같은 순수 호스트명입니다. 낮은 볼륨 테스트는 로그인 없이 가능하며, 응답은 기본 PNG라 <img> 태그에서 바로 사용할 수 있습니다.

브라우저 키와 서버 키의 차이는 무엇인가요?

브라우저 키는 프론트엔드 코드와 <img> 태그에 그대로 노출해도 안전합니다. 키에 등록된 허용 도메인을 기준으로 요청이 검증됩니다. 서버 키는 Authorization: Bearer 헤더로 백엔드에서만 사용해야 하며, 절대 브라우저로 노출되어선 안 됩니다.

어떤 출력 포맷을 지원하나요?

png(기본), webp, jpeg 세 가지를 지원합니다. format 파라미터를 생략하면 요청의 Accept 헤더로 자동 협상되며, 현대 브라우저에서 <img> 로 불러올 때 WebP 가 자동 반환됩니다.