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 auf einem opaken, themengerechten Hintergrund zurückgibt (weiß für hell, ein dunkles Neutral für dunkel). 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.
`frame`	`fill, original`	`fill`	`fill` füllt die Canvas (abzüglich Padding) mit dem visuellen Inhalt des Logos und verwirft Quell-Leerraum. `original` bewahrt die ursprüngliche Rahmung und Proportionen des Quell-Icons und behält App-Icon-artigen Randabstand.
`padding`	number	`10`	Rand je Seite um den gerahmten Inhalt, als % der Canvas (0–20, Schritt 5).
`shape`	`square, circle`	`square`	`square` ist die Standardrahmung. `circle` passt das Logo in einen einbeschriebenen Kreis, damit es in einem kreisförmigen Avatar nicht abgeschnitten wird — die Ausgabe ist weiterhin ein quadratisches Bild, ohne Transparenzmaske.
`part`	`full, logo, text`	`full`	Wählt aus, welcher Teil des Logos ausgeliefert wird — `full` (das gesamte Logo), `logo` (das Icon/Markenzeichen) oder `text` (der Schriftzug) — für Domains, deren Logo aufgeteilt wurde. Wenn der angeforderte Teil nicht verfügbar ist, wird auf das vollständige Logo zurückgefallen (oder es wird ein transparentes Bild zurückgegeben, wenn das Logo als separate Teile verwaltet wird). Teile können Rastergrafiken (PNG) sein und werden in ihren echten Farben dargestellt.
`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. Setzt auch den opaken Hintergrund: weiß für `light`, ein dunkles Neutral für `dark`.
`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.

Eine typische Anfrage mit den kanonischen Parametern:

GET https://api.clearlogo.dev/logo/github.com?size=128&frame=fill&padding=10&shape=square

Nur das Icon/Markenzeichen eines aufgeteilten Logos mit part anfordern:

GET https://api.clearlogo.dev/logo/github.com?size=128&part=logo

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.

Welche Rate-Limits gelten?

Pro-Schlüssel-Limits werden in den Antwort-Headern X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset zurückgegeben. Das Überschreiten des Limits gibt HTTP 429 mit einem Retry-After-Hinweis zurück, der angibt, wie viele Sekunden vor dem nächsten Versuch gewartet werden soll.

Kann ich einen transparenten Hintergrund oder einen quadratischen Zuschnitt erhalten?

Die Ausgabe ist immer ein opakes, quadratisches Bild — es gibt keine transparente Variante. Der Hintergrund entspricht dem theme: weiß für light und ein dunkles Neutral für dark. Innerhalb dieser quadratischen Canvas steuern Sie die Rahmung: frame (fill, original) wählt zwischen dem Füllen der Canvas mit dem Logo-Inhalt oder dem Bewahren der ursprünglichen Proportionen des Quell-Icons, padding (0–20, Schritt 5) setzt den Rand je Seite, und shape (square, circle) passt das Logo in einen einbeschriebenen Kreis, wenn auf circle gesetzt (weiterhin auf einem quadratischen Bild gerendert). Verwenden Sie size (zulässig: 16, 32, 48, 64, 96, 128, 192, 256, 512, 1024) für die genaue Pixelgröße. Für Domains, deren Logo aufgeteilt wurde, wählt part (full, logo, text) das gesamte Logo (full, Standard), das Icon/Markenzeichen (logo) oder den Schriftzug (text) und fällt auf das vollständige Logo zurück, wenn ein Teil nicht verfügbar ist (oder gibt ein transparentes Bild zurück, wenn das Logo als separate Teile verwaltet wird).