# API リファレンス

> ClearLogo は単一の HTTP エンドポイント `GET /logo/{domain}` を公開し、ドメインのロゴを一貫した比率と透過背景の PNG (または WebP/JPEG) として返します。匿名アクセスは低ボリュームのテストで動作し、本番トラフィックではブラウザキー (クライアント) またはサーバーキー (バックエンド) を使用します。

## エンドポイント

```
GET https://api.clearlogo.dev/logo/:domain
```

`:domain` はスキームやパスのない名前付きホスト名です。例えば `github.com`。API はデフォルトで `image/png` を返します。

## クエリパラメータ

| 名前 | 型 | デフォルト | 注記 |
| --- | --- | --- | --- |
| `size` | number | `128` | 出力の寸法 (ピクセル単位)。正方形のみ。許可される値: 16、32、48、64、96、128、192、256、512、1024。 |
| `content` | number | `80` | キャンバス内のロゴフットプリント (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` ヒントを含めます。

## よくある質問

### ドメインのロゴを取得するには?

`https://api.clearlogo.dev/logo/{domain}` に GET リクエストを送信してください。`{domain}` は `github.com` のような名前付きホスト名です。低ボリュームのテストにはログインは不要で、応答はデフォルトで PNG なので `<img>` タグで直接使用できます。

### ブラウザキーとサーバーキーの違いは?

ブラウザキーはフロントエンドコードや `<img>` タグに含めても安全です。リクエストはキーで設定された許可ドメインに対して検証されます。サーバーキーはバックエンドからの `Authorization: Bearer` ヘッダーで認証し、ブラウザに送信してはいけません。

### サポートされる出力フォーマットは?

`png` (デフォルト)、`webp`、`jpeg` の 3 つをサポートしています。`format` パラメータを省略すると、リクエストの `Accept` ヘッダーから自動ネゴシエーションされ、モダンブラウザで `<img>` を使用すると WebP が自動的に返されます。