エージェントと自動化

AI コーディングエージェントや自動化されたバックエンドに SpicyAPI を組み込むときは、このページを使ってください。API リファレンスの内容を、範囲が限られ、あとから検証できるワークフローにまとめています。公開されている仕様を調べ、モデルの入力を検証し、価格を確認し、1 回だけ作成し、安全に待ち、完了を確かめ、期限が切れる前に出力をコピーする、という流れです。

ツールを選ぶ

公式の npm パッケージは 4 つあり、どれも MIT ライセンスで、それぞれ個別にインストールします。パッケージごとに専用のガイドがあり、インストール方法、対応しているすべてのクライアントでの設定方法、完全なリファレンスをまとめています。

4 つのパッケージはどれも Node.js 22.13 以降が必要です。npx skills add で Skill をインストールする場合は、Node.js 22.20 以降が必要です。

Node.js 以外

公式 SDK はほかにも 4 つあります。どれも MIT ライセンスで、同じワークフロー（見積もる、冪等キーを付けて作成する、待つ、受け取る）を実装しています。

これらのパッケージは、表のとおりの名前で案内してください。各ガイドはインストールのコマンドから始まります。そのほかの言語からは、HTTP API を直接呼び出すか、OpenAPI の仕様からクライアントを生成してください。公開されていないコミュニティ製のラッパーを、公式 SDK として紹介しないでください。

依存パッケージを追加できない場合や、HTTP の呼び出しをそのまま見たい場合は、下にある 2 つのリファレンスクライアントをコピーして使えます。どちらも、言語のランタイム以外に何も使わずに同じワークフローを実装しています。依存を追加できるなら、その言語の公式 SDK を優先してください。

お金を使うには人の承認が必要

タスクの作成と再試行にはお金がかかり、受理されたタスクはキャンセルできません。そのため、どの経路も、まず人が金額を承認するように作られています。

• CLI： tasks create は先に見積もりを取り、金額を表示して Continue? [y/N] と尋ねます。この質問を飛ばせるのは --yes だけです。誰かがすでに価格を承認しているスクリプトの中でだけ使ってください。
• MCP： 課金されるツールはどれも、MCP クライアント自身の確認画面を通じて確認を求め、クライアントがそれをあなたに表示します。承認は必ずあなた自身が行ってください。エージェントが承認したり、クライアントを自動承認に設定したりすると、その歯止めがなくなります。
• 自分で作る自動化： createTask や retryTask を呼び出す前に、選んだモデル、入力の要約、見積もられた価格を見せて、はっきりした承認を得てください。課金されない正確な見積もりを POST /api/v1/jobs/quote で取得し、その quoteId と expectedCost を付けて送信します。こうしておけば、価格が変わったときに別の金額で課金されるのではなく、40901 で失敗します。見積もりとプロトコル互換を参照してください。

機械が読める情報源

いま知りたいことに答えられる、いちばん小さな資料から始めてください。そうすると、エージェントのコンテキストが正確に保たれ、コストも抑えられます。

OpenAPI の仕様とライブのモデルカタログを、守るべき契約として扱ってください。マーケティング用の例は説明のためのもので、スキーマの情報源ではありません。これらの資料はキャッシュしてかまいませんが、コードを生成する前や、リクエストが検証で失敗し始めたときには取得し直してください。

承認を挟んだ最小限の SDK の流れ

このスクリプトは、SDK を使った場合の承認の境目を示しています。まず見積もりを取り、--approved を渡さない限りそこで止まります。渡した場合は、見積もった価格でタスクを作成して完了を待ちます。インストール方法、すべてのメソッド、最初の結果を得るまでの完全な手順は TypeScript SDK のガイドに、メソッドの詳細はその API リファレンスにあります。

npm install @spicyapi/sdk
export SPICY_MODEL_ID="MODEL_ID_FROM_CATALOG"     # ライブカタログにある model の値
export SPICY_INPUT_JSON='{"prompt":"your prompt"}' # そのモデルの inputSchema に合っている必要がある

import { randomUUID } from "node:crypto";
import { SpicyClient } from "@spicyapi/sdk";

const client = new SpicyClient(); // SPICY_API_KEY を読み取る
const modelId = process.env.SPICY_MODEL_ID;
if (!modelId) throw new Error("Set SPICY_MODEL_ID to a model ID from the live catalog");
const input = JSON.parse(process.env.SPICY_INPUT_JSON ?? "{}");

// 無料：このリクエストそのものの価格を計算する。何も作成されず、何も仮押さえされない。
const quote = await client.quoteTask({ model: modelId, input });
console.log(`${quote.model}: up to $${quote.maxCharge}, quote valid until ${quote.expiresAt}`);

if (!process.argv.includes("--approved")) {
  console.log("Nothing was submitted. Re-run with --approved once a person has approved this amount.");
  process.exit(0);
}

// 有料：見積もった価格で同じリクエストを送信する。実際のシステムでは、
// 最初の試行の前に冪等キーを作成して保存し、タスク ID も保存しておく。
const accepted = await client.createTask(
  { model: modelId, input, quoteId: quote.quoteId, expectedCost: quote.estimatedCost },
  { idempotencyKey: randomUUID() },
);
console.log("accepted", accepted.taskId, "deadline", accepted.deadlineAt);

// 待機をやめてもタスクはキャンセルされない。あとでタスク ID を使って再開できる。
const task = await client.waitForTask(accepted.taskId, { timeoutMs: 30 * 60_000 });
console.log(JSON.stringify(task, null, 2));

npx --yes tsx run.mts              # 見積もりだけ。無料
npx --yes tsx run.mts --approved   # タスクを作成する。お金がかかる

拡張子を .mts にすると、ファイルが ES モジュールとして扱われます。トップレベルの await を使うには、これが必要です。既定の npm init で作ったプロジェクトでただの run.ts にすると、Top-level await is currently not supported with the "cjs" output format というエラーで失敗します。見積もりの有効期間は 5 分です。承認にそれより時間がかかった場合は、1 つ目のコマンドをもう一度実行してください。

本番のワークフロー

POST /api/v1/jobs/createTask
Authorization: Bearer $SPICY_API_KEY
Content-Type: application/json
Idempotency-Key: project-42-scene-07-v1

// 現在定義されている 4 つの終端状態。判断の基準は「非同期タスク」のページで、
// queued と running 以外の状態は、ここに載っていないものも含めてすべて終端として扱う。
const KNOWN_TERMINAL = ['succeeded', 'failed', 'canceled', 'expired'];

const deadline = Date.parse(accepted.deadlineAt) + 60_000;
let delay = 2_000;

while (Date.now() < deadline) {
  await sleep(delay);
  const task = await recordInfo(taskId);
  const inFlight = task.state === 'queued' || task.state === 'running';
  const assetsPending = task.state === 'succeeded' && task.output?.assets?.some((a) => a.pending);
  if (!inFlight && !assetsPending) {
    if (!KNOWN_TERMINAL.includes(task.state)) log.warn(`new terminal state: ${task.state}`);
    return task;
  }
  delay = Math.min(Math.round(delay * 1.5), 15_000);
}
throw new Error(`task ${taskId} exceeded the polling deadline`);

最小限の永続化レコード

再起動したあとでも安全に再開できるだけの状態を保存しておきます。

{
  "localRequestId": "project-42-scene-07-v1",
  "idempotencyKey": "project-42-scene-07-v1",
  "apiKeyName": "production backend",
  "taskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
  "model": "MODEL_ID_FROM_CATALOG",
  "approvedCost": "0.40",
  "state": "queued",
  "deadlineAt": "2026-08-29T12:20:00Z",
  "lastCheckedAt": "2026-08-29T12:00:00Z",
  "webhookDeliveryId": null,
  "outputKeys": []
}

MODEL_ID_FROM_CATALOG は、認証付きのライブカタログから選んだ正確な ID を表しており、そのまま送る文字列ではありません。どの API キーでタスクを作成したかを記録してください。そのタスクを読み取ったり再試行したりできるのは、そのキーだけです。署名付きのダウンロード URL を、長く使う識別子にしてはいけません。HTTP の 200 から成功と判断してもいけません。data.state を読んでください。

お金を使う前にモックで試す

非同期タスク、Webhook、エラーに書かれている応答の外枠に沿って、仕様どおりに振る舞うモックを手元に作ります。テスト用データには、次のケースを含めてください。

• queued → running → succeeded
• code: 200 かつ data.state: "failed" の、終端状態としての失敗
• 同じ taskId を返す、重複した createTask の応答
• もう一致しなくなった見積もり（40901）と、残高不足（40201）
• 正しい Webhook、無効な署名、再送された配信
• 429、503、通信のタイムアウト、ポーリングの締め切りを超えるタスク
• 発行し直す必要がある、期限切れのダウンロード URL

モックで確かめられるのは処理の組み立てであって、モデルの品質ではありません。公開する前に、本番で使うのとまったく同じモデルと入力の形で、小さな実際のタスクを実行してください。

受け入れチェックリスト

• 秘密情報はサーバー側の秘密情報ストレージにだけ置かれ、ログでは伏せられている。
• 組み込みは、フィールドを推測せず、現在のモデルのスキーマを取得している。
• 課金される呼び出しの前に、見積もられた価格を人が承認し、送信には quoteId と expectedCost が付いている。
• 論理的に 1 つのリクエストには、保存済みの Idempotency-Key が 1 つあり、常に同じ API キーと一緒に送られる。
• 処理を先に進める前に taskId が保存され、プロセスが再起動しても失われない。
• ポーリングは、待ち時間を延ばす方式（バックオフ）、最大間隔、実時間の締め切りを使っている。
• Webhook では、タイムスタンプ、生の本文のダイジェスト、HMAC を検証してから、配信 ID で重複を取り除いている。
• 終端状態での失敗は、HTTP ステータスや外枠の code ではなく、data.state から読み取っている。
• 必要な出力は、URL や保存期間の期限が切れる前に、自分のストレージにコピーされている。taskId とオブジェクトキーは突き合わせのために残しておくもので、保存期間が終わったあとにファイルを取得する手段としてあてにはしていない。
• ログには、プロンプトや秘密情報を含めずに、request_id、taskId、モデル、試行回数が残っている。
• モックのテストが、重複作成、再送、タイムアウト、レート制限、期限切れのメディアを網羅している。