本番で使うときの注意とエラー

1. 許可はキーを作るときに決まる

許可を後から変える API はありません。

成果テキストの許可が無いキーで /result を呼ぶと、resultText は null になり、resultTextWithheld に理由が入ります。

テキストだけの実行には、「成果テキスト」と「クラウド実行の起動」の両方を許可したキーを使います。許可が足りないときは、キーを作り直してください（最初の準備）。

2. 結果の中身を確かめる

エンジンが一時的に失敗すると、status は done なのに、resultText がエラーの文だけ、ということがあります。

status だけでなく、resultText が期待した形になっているかも確かめてください。

形が違うときは、やり直します。別のエンジンで送り直すのも有効です。

3. /result の waitS は最大 25 秒

1 回のリクエストでは、終わりまで待てないことがあります。

terminal が true になるまで、呼び続けてください。作成には、数分以上かかることがあります。

4. 定期の処理では、毎回まず回収する

ほかの仕事が無いときだけ /result を回収する作りにすると、仕事が続く間、回収がいつまでも後回しになります。

毎回の処理の最初に、回収を試してください。終わった結果がたまらなくなります。

5. 失敗を記録する

起動、回収、中身の確認のそれぞれで、失敗をログに残すか、通知してください。

どこで止まったかが分かります。

通信が切れて起動を送り直すときは、同じ Idempotency-Key で送ると、二重に起動しません（1 人で実行する）。

よくあるエラー

呼び出しの回数には、Base URL の側にも上限があります。既定では、1 つのキーで、起動は 24 時間に 100 単位（/launch は 1、/orchestrate は 3、params.requirementsImageGeneration: true を書くと 2 を足す）、読み取りは 5 分に 300 回までです。

上限と使った数を見る（/quota）

curl -s -X POST "https://www.kamui.ai/api/cloud/quota" \
  -H "x-kamui-api-key: kamui_sk_..." -H "Content-Type: application/json" -d '{}'
# → { "daily": { "used": 3, "limit": 100 }, "active": { "used": 1, "limit": 5 } }

• daily は、直近 24 時間に始めた実行の数と、その上限です。
• active は、今動いている実行の数と、同時実行の上限です。
• 数はアカウント全体で数えます。上の数字は例です。上限の値は、/quota で確かめてください。

コピーして使える最小のクライアント

Node.js 18 以上で動きます。追加の依存はありません。

実行を始め、終わるまで待ち、結果を表示します。

run.mjs として保存し、KAMUI_API_KEY=kamui_sk_... node run.mjs "作業の指示" で動かします。

// run.mjs — 追加の依存なし（Node 18 以上）
import { randomUUID } from "node:crypto";

const BASE = "https://www.kamui.ai/api/cloud";
const post = async (path, body, extraHeaders = {}) => {
  const r = await fetch(BASE + path, {
    method: "POST",
    headers: {
      "content-type": "application/json",
      "x-kamui-api-key": process.env.KAMUI_API_KEY,
      ...extraHeaders,
    },
    body: JSON.stringify(body),
  });
  const j = await r.json();
  if (!r.ok) throw new Error(`${path} ${r.status}: ${j.error ?? ""}`);
  return j;
};

// 起動: repoUrl を付けると Git で、省くとテキストで受け取る
const { runId } = await post(
  "/launch",
  {
    serverAuth: true,
    engine: "codex",
    prompt: process.argv[2] ?? "1+1 の答えだけを返してください",
  },
  { "Idempotency-Key": randomUUID() },
);
console.log("runId:", runId);

// 終わるまで待つ（waitS は 1 回で最大 25 秒）
let res;
do {
  res = await post("/result", { runId, waitS: 25 });
  console.log("status:", res.status);
} while (!res.terminal);

console.log(res.resultText ?? res.resultTextWithheld ?? JSON.stringify(res.artifact));