クラウド 3

1 人で実行する（POST /launch）

/launch は、選んだ 1 人の AI に、1 つの作業を頼みます。

エンジン、モデル、労力（effort）を 1 つ決めて動かすときは、ここを使います。

計画して作業を分けたいときは、メンバーが 1 人でも /orchestrate を使います。

リポジトリで作業する

curl -X POST "https://www.kamui.ai/api/cloud/launch" \
  -H "x-kamui-api-key: kamui_sk_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "serverAuth": true,
    "engine": "codex",
    "prompt": "README にセットアップ手順を足してください",
    "repoUrl": "https://github.com/you/repo",
    "baseBranch": "main",
    "params": { "autoPush": true }
  }'
# → { "runId": "<uuid>", "machineId": "..." }

作業の結果は、kamui-cloud/… のブランチに push されます。
repoUrl は、https://github.com/ で始まる GitHub のリポジトリだけ受け付けます。
返ってきた runId で、/result を呼びます。

Idempotency-Key（二重起動を防ぐ鍵）

起動のリクエストには、毎回新しい Idempotency-Key を付けます。

英数字と . _ : - を使った 16〜128 文字です。uuidgen の値が使えます。

付けないと、400（idempotency-key-required）になります。

通信が切れて送り直すときは、同じ鍵と、まったく同じ本文で送ります。24 時間以内なら、前と同じ応答が返り、二重には起動しません。このとき、応答に Idempotency-Replayed: true のヘッダーが付きます。

同じ鍵で本文を変えると、409（idempotency-conflict）になります。前の送信がまだ処理中なら、409（request-in-progress）になります。

テキストだけ受け取る（repoUrl を省く）

JSON や文章だけが欲しいときは、Git のリポジトリは要りません。

repoUrl を省くと、clone も push もしません。AI の最後の返事が、/result の resultText になります（artifact は {"type":"text"}）。

たとえば、定期の処理から記事、要約、翻訳、JSON の作成を頼み、返ってきた JSON を自分のデータベースに保存できます。

プロンプトは 40 万文字まで送れます。材料の文章も、プロンプトに入れて送れます。

この使い方には、「成果テキスト」を許可したキーが要ります（最初の準備）。

curl -X POST "https://www.kamui.ai/api/cloud/launch" \
  -H "x-kamui-api-key: kamui_sk_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "serverAuth": true,
    "engine": "codex",
    "title": "AI ニュース: 速報記事",
    "prompt": "あなたはニュース編集の担当です。\n決まり: ファイルの作成・編集、コマンドの実行、Web 検索はしないでください。前置き、後書き、コードフェンスは付けないでください。最後の返事で、次の JSON を 1 つだけ返してください:\n{\"title\":\"...\",\"article\":\"...(Markdown)\",\"tags\":[\"...\"]}\n\n=== 材料（集めた文章をここに入れる） ===\n..."
  }'
# → { "runId": "<uuid>" }   repoUrl が無いので、テキストで受け取る

終わるまで /result を繰り返し呼び、resultText を受け取ります。

waitS は、1 回で最大 25 秒待ちます。実行には、ふつう数分かかります。

while :; do
  R=$(curl -s -X POST "https://www.kamui.ai/api/cloud/result" \
    -H "x-kamui-api-key: kamui_sk_..." -H "Content-Type: application/json" \
    -d '{ "runId": "<uuid>", "waitS": 25 }')
  [ "$(echo "$R" | jq -r .terminal)" = "true" ] && break
done
echo "$R" | jq -r .resultText   # ← 記事の JSON

プロンプトの書き方

「ファイルを作らない、コマンドを動かさない」「最後の返事は JSON だけ」と、はっきり書きます。書かないと、AI が内容をファイルに書いてしまい、最後の返事に入らないことがあります。
出力の形は、例を見せて決めます。
受け取る側でも、前置きやコードフェンスを取り除き、外側の JSON を取り出します。壊れた JSON は、直してから使います。

パラメーター

「Fuga の設定」の列は、デスクトップの Fuga の入力欄にある設定のうち、同じ働きのものです。

params を省くと、従来どおりの動きになります。

パラメーター	型	必須	既定	Fuga の設定	説明
`prompt`	string	必須	—	入力欄	AI への作業の指示。40 万文字まで。
`serverAuth`	true	必須	—	—	クラウド金庫の認証で動かす。API キーで起動するときは、必ず `true` にする。
`engine`	string	任意	codex	エージェントプール	claude、codex、gemini、qwen、grok、kimi、opencode のどれか。金庫に認証があるエンジンだけ動く。
`model`	string	任意	エンジンの既定	モデル	エンジンのモデル ID。サーバーが許可したモデル ID だけ受け付ける。それ以外は 400（`invalid-model`）。
`effort`	string	任意	エンジンの既定	労力	推論の深さ。low、medium、high、xhigh、max のどれか。効き方はエンジンによる。
`repoUrl`	string	任意	—	—	作業する GitHub のリポジトリ（`https://github.com/…`）。省くとテキストだけを返す。
`baseBranch`	string	任意	リモートの既定	—	clone の元、`autoMerge` の取り込み先のブランチ。
`title`	string	任意	—	—	実行の題名。200 文字まで。`/result` の `title` に返る。
`idleTimeoutS`	number	任意	0	—	1 ターン目の後に、追加の指示を待つ秒数。0 は 1 ターンで終わる。最大 3600。この Base URL には追加の指示を送る窓口が無いので、ふつうは 0 のままにする。
`params.autoMerge`	boolean	任意	false	自動マージ	終わったら `baseBranch` に取り込む。fast-forward できないときなどは取り込まず、実行は done のまま終わる。結果は `/result` の `autoMerge` で確かめる。
`params.autoPush`	boolean	任意	true	自動プッシュ	作業のブランチを origin に push する。false にすると push しない。
`params.requirementsGeneration`	boolean	任意	false	要件定義の生成	実装の前に、要件定義の HTML を作る。
`params.requirementsImageGeneration`	boolean	任意	false	要件定義の画像生成	要件定義に画面の案の画像を入れる。金庫に fal のキーが要る。`requirementsGeneration` がオフのときは、オフになる。

使えない機能

パソコンの操作とブラウザーの操作（params.pcOperation・params.webOperation）は、パソコンの Fuga 専用です。true にすると 400 になります。
TODO、不具合の報告、機能の要望、定期実行、トリガーは、実行を始めない別の経路です。この API の対象外です。