API-Referenz
Ein Endpoint, ein paar Regler, zwei Authentifizierungsmodi.
Benötigen Sie einen Migrationspfad vor der Referenz?
Lesen Sie zuerst den Clearbit-Migrationsleitfaden oder den logo-API-Käuferleitfaden.
ClearLogo stellt einen einzigen HTTP-Endpoint,
GET /logo/{domain}, bereit, der ein PNG (oder WebP/JPEG) des Domain-Logos mit konsistentem Seitenverhältnis und transparentem Hintergrund zurückgibt. Anonyme Nutzung funktioniert für Tests mit geringem Volumen; Produktionsverkehr verwendet einen Browser-Schlüssel (Client) oder einen Server-Schlüssel (Backend).
Endpoint
GET https://api.clearlogo.dev/logo/:domain
:domain ist ein einfacher Hostname ohne Schema oder Pfad, z. B. github.com. Die API gibt standardmäßig image/png zurück.
Query-Parameter
| Name | Typ | Standard | Hinweise |
|---|---|---|---|
size | number | 128 | Ausgabedimension in px. Nur Quadrat. Zulässige Werte: 16, 32, 48, 64, 96, 128, 192, 256, 512, 1024. |
content | number | 80 | Logo-Fußabdruck innerhalb der Canvas (50–100, Schritt 5). |
format | png | webp | jpeg | png | Ausgabeformat. Wird automatisch vom Accept-Header ausgehandelt — moderne Browser erhalten WebP automatisch über <img>. |
theme | light | dark | light | Gibt die dunkle Variante zurück, wenn verfügbar, sonst fällt auf hell zurück. |
token | string | — | Browser-Schlüssel, der von Client-Code verwendet wird. Origin oder Referer müssen einer zulässigen Domain auf dem Schlüssel entsprechen. |
Authentifizierung
Anonyme Anfragen funktionieren für Tests mit geringem Volumen. Verwenden Sie für Produktionsverkehr einen Browser-Schlüssel (Client) oder einen Server-Schlüssel (Backend):
Browser
<img
src="https://api.clearlogo.dev/logo/example.com?token=YOUR_BROWSER_KEY"
alt="" />
Server
curl \
-H "Authorization: Bearer YOUR_SERVER_KEY" \
"https://api.clearlogo.dev/logo/example.com"
Rate-Limits
Pro-Schlüssel-Limits werden in X-RateLimit-*-Headern zurückgegeben. Wenn Sie diese überschreiten, antwortet die API mit 429 und enthält einen Retry-After-Hinweis.
Häufige Fragen
Wie erhalte ich ein Logo für eine Domain?
Senden Sie eine GET-Anfrage an https://api.clearlogo.dev/logo/{domain}, wobei {domain} ein einfacher Hostname wie github.com ist. Für Tests mit geringem Volumen ist keine Anmeldung erforderlich. Die Antwort ist standardmäßig ein PNG und funktioniert direkt in <img>-Tags.
Was ist der Unterschied zwischen einem Browser- und einem Server-Schlüssel?
Ein Browser-Schlüssel kann sicher in Frontend-Code und <img>-Tags eingesetzt werden; Anfragen werden gegen die auf dem Schlüssel konfigurierten zulässigen Domains validiert. Ein Server-Schlüssel authentifiziert sich über den Authorization: Bearer-Header vom Backend und darf den Browser niemals erreichen.
Welche Ausgabeformate werden unterstützt?
png (Standard), webp und jpeg. Wenn der format-Parameter weggelassen wird, verhandelt ClearLogo den Inhalt anhand des Accept-Anfrage-Headers — moderne Browser erhalten WebP automatisch, wenn die API über ein <img>-Tag geladen wird.