Atomic AI API — 技術ドキュメント

v1.0 ／ベースURL: https://<host>/api（既存サービスに別パス /api でmount）

認証

全エンドポイント（/health を除く）で HTTPヘッダ X-API-Key が必須。無い/不正 → 401。

レート制限・上限・プラン

・レート制限: キー別スライディング60s（plan依存）→ 超過 429。
・月次トークン上限: plan依存（monthly_tok）→ 超過 429。
・使用量はキー×月で記録（/usage で確認）。

plan	monthly_tok	rate/min	price
free	100,000	10	未確定
starter	2,000,000	60	未確定
pro	20,000,000	240	未確定
enterprise	無制限	1200	未確定

※価格は準備中（事業判断・弁護士レビュー前のため非掲載）。現時点で課金は行いません（計測のみ）。

共通仕様

・リクエスト/レスポンスは JSON。
・エラー: {"detail":"..."}（HTTP 400 / 401 / 429 / 503）。
・構造化ログ: 1リクエスト=1 JSON行（request_id / key_prefix / endpoint / status / tok_in / tok_out / duration_ms）。

エンドポイント

GET /health

認証不要。EP一覧と pricing/billing 状態を返す。

{"ok":true,"version":"1.0","endpoints":["/generate","/edit","/assemble","/atomize","/search"],
 "pricing":"config-only / 未確定","billing":"not-implemented (metering only)"}

POST /edit （本丸＝ことばで直す）

既存HTMLを最小コンテキストで編集（全文を読み直さない＝削減の源）。

入力: code(必須・編集対象HTML) / query(必須・自然文の指示) / meta_atom(任意)

出力: ok(反映をbody確認できた時のみtrue＝偽の成功なし) / applied(反映件数) / new_code / tokens{A_metaatom_in,B_fullread_in} / input_saved_pct / candidates(一意に特定できない時のみ)

対象が無い指示は可能なら追加で反映し、一意に特定できない時のみ候補を提示します。

レスポンス例（大ページ・実測値）:

{"ok":true,"applied":1,"new_code":"<html>...</html>",
 "tokens":{"A_metaatom_in":2377,"B_fullread_in":20204},"input_saved_pct":88.2,"plan":"pro"}

POST /generate

クエリから新規サイトHTMLを生成（atom再利用＋必要分のみ生成）。

入力: query(必須・作りたいサイトの自然文)

出力: code(HTML) / meta_atom / reuse(再利用atom数) / gen(新規生成数) / tokens{in,out} / precision

レスポンス例（T8実測 N=12 の1件・和食レストラン）:

{"reuse":14,"gen":0,"tokens":{"in":3342,"out":2929},"plan":"pro"}
// code(HTML 約56KB)・meta_atom は省略。reuse率が高いほど out トークンは小

POST /atomize

HTMLを再利用可能な構造（meta atom）へ分解。固有名はsanitize。

入力: code(必須) / name(任意) ／出力: meta_atom / precision / sanitize_flags

POST /assemble

既存atomを合成してサイト生成（再利用＝0トークン）。

入力: atom_ids[](必須) / theme(任意) / content(任意) ／出力: ok / code / names / tokens{in:0,out:0}

GET /search?query=...&top_k=8

用途の自然文で類似atomを意味検索（embedding cos類似）。

出力: atoms[{name,intent,score}] ／検索エンジン不在時 → 503

※日本語クエリは必ずURLエンコード（curlは -G --data-urlencode）。

レスポンス例（実機）:

{"atoms":[{"name":"Tpl_471985","intent":"予約フォーム","score":0.71},
 {"name":"Tpl_832022","intent":"予約ボタン","score":0.518}],"plan":"pro"}

GET /usage

キーの当月使用量・残量・価格状態。

出力: plan / month / tokens_used / monthly_cap / remaining / price_jpy(null) / note

レスポンス例:

{"plan":"pro","month":"2026-06","tokens_used":12345,"monthly_cap":20000000,
 "remaining":19987655,"price_jpy":null,"note":"価格は未確定(事業判断待ち)・課金は未実装(計測のみ)"}

エラー例

認証なし → 401:

{"detail":"invalid or missing X-API-Key"}

クイックスタート

# 疎通
curl https://<host>/api/health

# ことばで直す
curl -X POST https://<host>/api/edit \
  -H 'Content-Type: application/json' -H 'X-API-Key: <your-key>' \
  -d '{"code":"<html>...</html>","query":"見出しを春の特集に変更して"}'

# 意味検索(日本語はURLエンコード)
curl -G https://<host>/api/search -H 'X-API-Key: <your-key>' \
  --data-urlencode 'query=予約フォーム' --data-urlencode 'top_k=3'

SDK（Python / TypeScript / curl）も提供。導入のご相談はお問い合わせから。

本ドキュメントは現時点の実装に基づく案内です。価格・課金は未確定（準備中）。利用規約等は弁護士レビュー前のドラフトであり正式な法的効力を持ちません。