Question 1

ClearLogo 是什么？

Accepted Answer

ClearLogo 是一个 logo API，为任何域名返回单个干净的图像。与通用 logo 源不同，它专注于展示：每个响应都是背景感知的、自动裁剪的，并且比例适配，使 logo 在仪表盘、CRM、公司表格和其他产品界面中保持一致。

Question 2

我需要注册才能尝试 API 吗？

Accepted Answer

不需要。您可以立即向 https://api.clearlogo.dev/logo/{domain} 发送匿名请求进行低流量测试 — 无需密钥。对于生产流量，您需要从 仪表盘 获取浏览器密钥或服务器密钥。

Question 3

我需要后端服务器来使用 ClearLogo 吗？

Accepted Answer

不需要。浏览器密钥可让您从前端代码直接在 <img> 标签中嵌入 logo URL。请求由 Origin/Referer 匹配针对您在密钥上配置的允许域进行验证。仅当您更喜欢从后端使用 Authorization: Bearer 身份验证时才使用服务器密钥。

Question 4

我如何开始？

Accepted Answer

最快的方式：打开 playground，粘贴几个代表性域名，并查看输出在您的 UI 中的外观。满意后，在 仪表盘 中创建生产密钥，并将 URL 替换到您的代码中。

Question 5

ClearLogo 的最佳用例是什么？

Accepted Answer

ClearLogo 非常适合任何 logo 并排显示且视觉一致性很重要的地方 — 公司表格和目录、CRM 账户列表、充实 UI、销售工具和内部仪表盘。如果您只需要一个一次性 logo，并且在服务器端缓存后面，而展示一致性不是问题，通用源可能就足够了。

Question 6

浏览器密钥和服务器密钥有什么区别？

Accepted Answer

浏览器密钥 (pk_…) 可以安全地用于前端代码和 <img> 标签。请求通过匹配 Origin 或 Referer 标头与您配置的允许域进行身份验证。服务器密钥 (sk_…) 通过后端的 Authorization: Bearer YOUR_KEY 进行身份验证，绝不能暴露给浏览器。

Question 7

我如何将浏览器密钥限制到特定域？

Accepted Answer

在 仪表盘 中，打开密钥的设置，启用 仅允许的域，并逐行添加您的域。支持 *.example.com 这样的通配符表示法用于子域。

Question 8

启用域限制后，没有 Referer 标头的请求会发生什么？

Accepted Answer

它们会被阻止。直接流量和使用 Referrer-Policy: no-referrer 或 same-origin 发送的请求在域限制处于活跃状态后会失败。有效的策略包括 strict-origin-when-cross-origin、origin、origin-when-cross-origin 和 unsafe-url。您可以通过在启用限制前在浏览器的网络选项卡中检查 img.logo.dev 请求上的 Referer 标头来验证您的设置。

Question 9

我如何轮换或替换 API 密钥？

Accepted Answer

在 仪表盘 中创建新密钥，更新您的集成以使用它，然后删除旧密钥。如果您需要紧急轮换，请联系 support@clearlogo.dev。

Question 10

ClearLogo 返回哪些图像格式？

Accepted Answer

png 是默认格式。您可以通过 format 查询参数请求 webp 或 jpeg。当省略 format 时，API 从 Accept 请求标头进行内容协商 — 通过 <img> 加载的现代浏览器会自动接收 WebP。

Question 11

"背景感知"输出是什么意思？

Accepted Answer

ClearLogo 检测品牌的 logo 是为彩色还是深色背景设计的，并在响应图像中保留该背景。这防止了透明 logo 在浅色表面上看起来损坏的常见问题。

Question 12

有哪些可用尺寸？

Accepted Answer

size 参数接受 2 的幂：16、32、48、64、96、128、192、256、512 和 1024 像素。图像始终是正方形。默认值为 128 像素。超出此列表的值将自动吸附到最近的允许值（同距离时取较大值）。

Question 13

`theme` 参数有什么作用？

Accepted Answer

设置 theme=dark 会在可用时返回 logo 的深色背景变体。如果不存在深色变体，API 将回退到标准版本。

Question 14

速率限制是什么？

Accepted Answer

限制因计划而异 — 有关详细信息，请参阅 定价页面。每个密钥的使用情况在 X-RateLimit-Limit、X-RateLimit-Remaining 和 X-RateLimit-Reset 响应标头中返回，因此您可以实时监控消耗。

Question 15

当我超过速率限制时会发生什么？

Accepted Answer

API 返回 HTTP 429，其中包含 Retry-After 标头，指示重试前要等待的秒数。我们会在采取任何进一步行动前与您联系 — 未经警告不会中断服务。

Question 16

我如何检查当前使用情况？

Accepted Answer

实时使用情况在 仪表盘 中可见。您也可以在任何 API 响应上读取 X-RateLimit-Remaining 标头。

Question 17

域的 logo 未显示 — 我应该检查什么？

Accepted Answer

按照此清单进行操作：(1) 确认域是没有方案或路径的裸主机名，例如 github.com 而不是 https://github.com/；(2) 检查您的 API 密钥有效且未过期；(3) 如果启用了域限制，验证是否发送了 Referer 标头；(4) 检查响应状态代码 — 404 表示找不到该域的 logo，401 表示身份验证问题，429 表示速率限制。

Question 18

域的 logo 看起来错误或过时 — 我能做什么？

Accepted Answer

请在 support@clearlogo.dev 与我们联系，提供域名和有关看起来不正确之处的说明。我们会审查并更新资源。

Question 19

我收到 401 错误 — 这是什么意思？

Accepted Answer

401 意味着请求未经身份验证。对于浏览器密钥，确保包含 token 查询参数，并且 Origin/Referer 标头与允许的域匹配。对于服务器密钥，确保存在 Authorization: Bearer YOUR_KEY 标头，并且密钥未被删除。

Question 20

logo 在生产中加载，但在本地开发中不加载 — 我如何修复？

Accepted Answer

在 仪表盘 中将 localhost（或 localhost:3000、localhost:5173 等）添加到您的密钥的允许域。API 与精确来源匹配，因此如果您的开发服务器使用非标准端口，请包含该端口。在分发密钥前删除本地条目，或创建单独的开发密钥。

Question 21

我在浏览器中看到 CORS 错误 — 我如何修复？

Accepted Answer

API 设置宽松的 CORS 标头，因此 CORS 错误通常表示缺少或被阻止的 Referer 标头，而不是真正的 CORS 问题。检查您页面的 Referrer-Policy — no-referrer 之类的策略会防止发送 Referer 标头，这会在域限制处于活跃状态时导致请求失败。也检查 <img> 标签本身：referrerpolicy="no-referrer" 或 referrerpolicy="same-origin" 属性会覆盖页面级策略，并从该特定请求中删除 Referer。

Question 22

有哪些可用计划？

Accepted Answer

ClearLogo 为低流量使用提供免费计划，为生产流量提供付费计划。有关当前计划详情和请求限制，请参阅 定价页面。

Question 23

我如何升级计划？

Accepted Answer

访问 仪表盘 并从您的计划卡中选择 升级。您将被带到账单页面，您可以在其中选择计划并完成付款。

Question 24

我可以取消订阅吗？

Accepted Answer

可以。您可以随时从 仪表盘 取消。您的计划将在当前计费周期结束时保持活跃。

帮助与常见问题

快速开始

API 密钥和身份验证

输出和格式

速率限制和使用

故障排除

账单和计划

还有问题吗？