API 参考

一个端点，几个参数，两种认证方式。

需要在查看参考前确定迁移路径?

ClearLogo 仅暴露一个 HTTP 端点 GET /logo/{domain}，返回该域名的 logo——以一致的比例渲染在不透明、匹配主题的背景（浅色为白色，深色为深中性色）上的 PNG（或 WebP/JPEG）。匿名调用适用于低流量测试；生产流量使用浏览器密钥（客户端）或服务器密钥（后端）。

端点

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` 用 logo 的视觉内容填满画布（减去边距），丢弃源文件留白。`original` 保留源图标的原始框架和比例，保持类 app 图标风格的四周留白。
`padding`	number	`10`	框架内容四周的边距，以画布百分比表示（0–20，步长 5）。
`shape`	`square, circle`	`square`	`square` 为标准框架。`circle` 将 logo 缩放到内切圆范围内，使其在圆形头像中不会被裁剪——输出仍为方形图片，不附加透明遮罩。
`part`	`full, logo, text`	`full`	选择要返回的 logo 部分——`full`（完整 logo）、`logo`（图标/标志）或 `text`（字标）——适用于已拆分 logo 的域名。若请求的部分不可用，则回退到完整 logo（对于以独立部分管理的 logo，则返回透明图片）。各部分可能为光栅格式（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 仅请求已拆分 logo 的图标/标志：

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 提示。

常见问题

如何获取域名的 logo?

向 https://api.clearlogo.dev/logo/{domain} 发送 GET 请求，其中 {domain} 是 github.com 这样的裸主机名。低流量测试无需登录，响应默认是 PNG，可直接用于 <img> 标签。

浏览器密钥和服务器密钥的区别是什么?

浏览器密钥可以安全地放在前端代码和 <img> 标签中；请求会根据您在密钥上配置的允许域名进行验证。服务器密钥通过后端的 Authorization: Bearer 头进行认证，绝不能传到浏览器。

支持哪些输出格式?

png（默认）、webp 和 jpeg。省略 format 参数时，ClearLogo 会根据请求的 Accept 头进行内容协商 — 通过 <img> 标签加载时，现代浏览器会自动获得 WebP。

速率限制是多少?

按密钥的限制通过 X-RateLimit-Limit、X-RateLimit-Remaining 和 X-RateLimit-Reset 响应标头返回。超出限制时返回 HTTP 429，并附带 Retry-After 提示，指示重试前需等待的秒数。

能获取透明背景或方形裁剪吗?

输出始终是不透明的方形图片——没有透明变体。背景与 theme 匹配：light 为白色，dark 为深中性色。在该方形画布内，您可通过以下参数控制框架：frame（fill, original）在"用 logo 内容填满画布"与"保留源图标原始比例"之间选择；padding（0–20，步长 5）设置四周边距；shape（square, circle）设为 circle 时将 logo 嵌入内切圆内（仍渲染为方形图片）。使用 size（允许值：16, 32, 48, 64, 96, 128, 192, 256, 512, 1024）指定精确像素尺寸。对于已拆分 logo 的域名，part（full, logo, text）可选择完整 logo（full，默认）、图标/标志（logo）或字标（text），若请求的部分不可用则回退到完整 logo（对于以独立部分管理的 logo，则返回透明图片）。