# colors-cc.top — エージェント・LLM向けドキュメント
> UI用の画像、配色、色を作成する、無料のステートレスAPIです。

## APIのベースURL
https://api.colors-cc.top

## エージェントが守るルール
1. 記載されているパラメーターだけを使用してください。
2. URL内のHEX色の # は、必ず %23 にエンコードしてください。
3. 画像URLをMarkdownの ![説明](URL) またはHTMLの <img> に直接埋め込んでください。SVGを取得して再エンコードしないでください。
4. 幅と高さは50〜4000ピクセルの範囲に自動調整されます。
5. プレースホルダーの文字は100文字までです。超過分は切り詰められます。

## 1. グラデーションSVGプレースホルダー
GET https://api.colors-cc.top/placeholder
軽量なSVG画像を、サイズ、文字、配色、効果を指定して作成します。

- w / width：幅。初期値800、範囲50〜4000ピクセル。
- h / height：高さ。初期値400、範囲50〜4000ピクセル。
- text：中央の文字。URLエンコードが必要です。省略時はサイズを表示し、最大100文字です。
- effect：効果。static, fluid, breathe, holographic, mesh。APIの初期値はstaticです。
- palette：HEX、RGB、HSL形式の色をカンマで区切って2〜10色指定します。省略時はランダムな2色です。
- speed：静止以外の効果の周期。初期値10秒、範囲1〜30秒。
- attribution：小さなブランドの透かし。初期値true、falseまたは0で非表示になります。

### 使用例
1200×630のバナー：
<img src="https://api.colors-cc.top/placeholder?w=1200&h=630&text=Hero+Banner" alt="バナー">
暖色のメッシュ画像：
<img src="https://api.colors-cc.top/placeholder?w=800&h=400&effect=mesh&palette=%23FFD6A5,%23FFADAD,%23E2A0FF" alt="暖色のメッシュ画像">
ホログラムのアニメーション：
<img src="https://api.colors-cc.top/placeholder?w=800&h=400&effect=holographic&palette=%2300FF41,%2300B8FF&speed=5" alt="ホログラム">

レスポンス：SVG画像。Cache-Control: public, max-age=31536000, immutable

## 2. 動くグラデーションSVG
GET https://api.colors-cc.top/fluid-placeholder
/placeholder?effect=fluid の別名です。色がなめらかに変化するアニメーション画像を作成します。
w、h、palette、speed、text、attributionは同じ指定方法です。初期サイズは800×400、周期10秒、文字は任意です。

オーロラ風のバナー：
<img src="https://api.colors-cc.top/fluid-placeholder?w=1200&h=400&palette=%2300FF41,%2300B8FF,%237000FF" alt="オーロラのバナー">
文字付きのサイバーパンク背景：
<img src="https://api.colors-cc.top/fluid-placeholder?w=800&h=600&palette=%23FCEE09,%23FF003C,%2300B8FF&speed=5&text=Welcome" alt="サイバーパンクの背景">
レスポンス：アニメーションSVG。キャッシュヘッダーは通常のプレースホルダーと同じです。

## 3. ランダムな色
GET https://api.colors-cc.top/random
HEX、RGB、タイムスタンプをJSONで返します。
例：{"hex":"#A1B2C3","rgb":"rgb(161, 178, 195)","timestamp":"2024-03-12T10:30:00.000Z"}
ボタンの色を選ぶ場合：fetch('https://api.colors-cc.top/random')
サンプルデータに複数のランダム色が必要な場合は、ループからこのエンドポイントを呼び出します。

## 4. テーマ別の配色
GET https://api.colors-cc.top/palette?theme={theme_name}
theme：cyberpunk, vaporwave, retro, monochrome。初期値はcyberpunkです。
テーマに応じた配色をJSONで返します。同じテーマの再取得で別の配色になるとは限りません。
例：{"theme":"cyberpunk","colors":["#FCEE09","#00FF41","#00B8FF"],"count":3}
サイバーパンク配色：fetch('https://api.colors-cc.top/palette?theme=cyberpunk')
レトロ配色：fetch('https://api.colors-cc.top/palette?theme=retro')

## 5. カラーコード変換
GET https://api.colors-cc.top/convert?{param}={value}
次のうち1つの入力パラメーターだけを指定してください。
- hex：%23FF5733 または FF5733
- rgb：rgb(255,87,51)
- hsl：hsl(10,100%,60%)
- cmyk：cmyk(0%,65%,80%,0%)
レスポンス：{"hex":"#FF5733","rgb":"rgb(255, 87, 51)","hsl":"hsl(10, 100%, 60%)","cmyk":"cmyk(0%, 66%, 80%, 0%)"}
入力エラー：HTTP 400、{"error":"Invalid color format"}
HEXからRGB：fetch('https://api.colors-cc.top/convert?hex=%23FF5733')
HSLからHEX：fetch('https://api.colors-cc.top/convert?hsl=hsl(200,50%,50%)')

## 6. CSS標準色名
GET https://api.colors-cc.top/all-names
標準色名からHEXへの対応表をJSONで返します。
例：{"AliceBlue":"#F0F8FF","Tomato":"#FF6347"}
Tomatoの値が必要な場合は、取得したオブジェクトの data.Tomato を参照してください。
CSSの識別子は翻訳せず、そのまま使用します。

## よくある誤り
- 誤：palette=#FF0000,%230000FF ／ 正：palette=%23FF0000,%230000FF
- 範囲外のサイズは自動調整されます。w=800&h=600など、有効なサイズを指定してください。
- SVGを取得・再エンコードせず、URLを <img> に直接使用してください。
- paletteには少なくとも2色が必要です。例：palette=%23FF0000,%230000FF

## 契約上の上限
- サイズ：50〜4000ピクセル
- 配色：2〜10色
- 周期：1〜30秒
- 文字：最大100文字

## 呼び出し回数
APIドキュメント上、すべてのエンドポイントは無料で回数制限はありません。

## ブラウザーで使うツール
- プレースホルダー：https://colors-cc.top/ja
- 色変換：https://colors-cc.top/ja/tools/converter
- 配色：https://colors-cc.top/ja/tools/random-palette
- CSS色名：https://colors-cc.top/ja/tools/color-names
- 動くSVG：https://colors-cc.top/ja/tools/fluid-placeholder
- 画像圧縮・透かし・配置：https://offline-tools.colors-cc.top/image-compress/ — 別アプリです。端末内で処理し、画像をアップロードしません。