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。
`content`	number	`80`	canvas 内的 logo 占比(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 参数时,ClearLogo 会根据请求的 Accept 头进行内容协商 — 通过 <img> 标签加载时,现代浏览器会自动获得 WebP。