# ブランディングアセットをアップロードする

`POST /v1/branding/assets` · 権限 `branding:write`

ホストされるログインページで使う画像（ロゴ、ファビコン、背景画像）をアップロードします。レスポンスの `id` は、テーマのフィールド `logo`、`favicon`、`background_image` に設定する値です（[ブランディングを更新する](./update.md)を参照）。画像は公開後にログインページへ表示されます。

すべての画像は隔離されたプロセスでデコードされ、最大 1024 × 1024 ピクセルの PNG に再エンコードされます。メタデータはすべて削除されます。ファビコンには 32 px と 180 px の版も作成されます。`id` は処理後の PNG の SHA-256 です。同じフィールドに同じ画像を再度アップロードすると、既存のアセットが `200 OK` で返されます。

受け付ける形式は PNG、JPEG、WebP で、ICO はファビコンのみ受け付けます。SVG は受け付けません。フォントのアップロードは利用できません。

1 つの環境に保存できるアセットは最大 200 個、合計 50 MB です。

## リクエスト

本文は `multipart/form-data` で、ファイルは最大 1 MiB です。

| パート | 型 | 必須 | 説明 |
|---|---|---|---|
| `kind` | string | はい | `logo`、`favicon`、`background_image` のいずれか。 |
| `file` | file | はい | 画像。最大 1 MiB、各辺 8192 ピクセル以内。 |

`Idempotency-Key` を使う場合、再試行では multipart の境界（boundary）を含めて、まったく同じバイト列を送信してください。

## レスポンス

新しいアセットには `201 Created`、同じフィールドに同じ画像が既にアップロードされている場合は `200 OK` を返します。

```json
{
  "id": "3f0c…e91a",
  "kind": "favicon",
  "url": "https://acme.eu1.keenauth.app/assets/3f0c…e91a.png",
  "width": 256,
  "height": 256,
  "byte_size": 48213,
  "source_format": "ico",
  "favicon_32_url": "https://acme.eu1.keenauth.app/assets/9b1d…04c2.png",
  "favicon_180_url": "https://acme.eu1.keenauth.app/assets/c7e2…5a10.png",
  "created_at": "2026-10-19T20:30:00Z"
}
```

`byte_size` は、そのアセットとして保存されたすべての PNG のサイズの合計で、クォータに含まれます。

## エラー

| HTTP | code | 発生条件 |
|---|---|---|
| 400 | `malformed_request` | multipart 本文を読み取れない、または `kind` と `file` 以外のパートが含まれています。 |
| 401 | `unauthenticated` | 認証情報がない、無効である、または取り消されています。 |
| 403 | `insufficient_permissions` | 認証情報に必要な権限がありません。 |
| 403 | `quota_exceeded` | 環境に既に 200 個のアセットまたは 50 MB があります。 |
| 413 | `payload_too_large` | ファイルが 1 MiB を超えています。 |
| 415 | `unsupported_media_type` | 本文が `multipart/form-data` ではない、またはファイルが受け付けられない形式です（`errors[]` の `unsupported_media_type`、`svg_not_allowed`、`ico_favicon_only`）。 |
| 422 | `validation_failed` | `kind` または `file` がないか無効です（フォントの場合は `/kind font_upload_disabled`）。または画像を使用できません: `invalid_image`、`image_too_large`、`image_dimensions_too_large`、`image_output_too_large`、`image_processing_limit`。 |
| 422 | `idempotency_key_reuse` | 同じ `Idempotency-Key` が別の本文で使われました。 |
| 429 | `rate_limited` | レート制限を超えました。`Retry-After` の時間が経過してから再試行してください。 |
| 503 | `service_unavailable` | アセットストレージが一時的に利用できません。`Retry-After` の時間が経過してから再試行してください。 |

## 例

```bash
curl -X POST https://api.eu.keenauth.com/v1/branding/assets \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -F kind=logo \
  -F file=@logo.png
```

CLI の場合:

```bash
keenauth branding assets upload --kind logo --file logo.png
```