# 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 必须与密钥上允许的域名匹配。 |

## 认证

匿名请求适用于低流量测试。对于生产流量,使用浏览器密钥(客户端)或服务器密钥(后端):

**浏览器**

```html
<img
  src="https://api.clearlogo.dev/logo/example.com?token=YOUR_BROWSER_KEY"
  alt="" />
```

**服务器**

```bash
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。