用語集

API キーから Webhook まで、このドキュメントで使うすべての用語を、SpicyAPI での意味と詳しい説明があるページとあわせて、わかりやすい言葉で解説します。

SpicyAPI は API として提供される製品なので、このドキュメントには技術的な用語が出てきます。このページでは、それぞれの用語をわかりやすい言葉で説明します。並び順は英語の用語名のアルファベット順です。各項目は 3 つの部分に分かれています。一般的な意味、SpicyAPI での意味、そして詳しい説明が載っているページです。

ほかのページからも各項目へ直接リンクしているので、どこかで引っかかった言葉があれば、たいていここに載っています。全体像をつかみたい場合は、SpicyAPI のしくみから読み始めてください。

Agent Skill

AI コーディングアシスタントが作業を始める前に読む、文章で書かれた手順書をまとめたフォルダーです。新しく来た同僚に渡す業務マニュアルのようなものです。プログラムは含まれておらず、それ自体が何かを実行することはありません。

SpicyAPI では： @spicyapi/skill として公開されている公式の Skill が、Claude Code、Codex、Cursor などのアシスタントに SpicyAPI の正しい使い方を教えます。推測せずにライブカタログを読む、有料の作業の前に価格を見せる、冪等キーを使い回す、API キーを絶対にコードに貼り付けない、といった内容です。インストールは npx skills add spicyapi-ai/spicy-skill で行います。MCP サーバーと一緒に使うと効果的です。

詳しくは： Agent Skill

API

application programming interface（アプリケーション・プログラミング・インターフェース）の略で、あるプログラムが別のプログラムに送れるリクエストと、それに対して返ってくる応答を、あらかじめ決めておいたものです。Web サイトは人がクリックするために作られていますが、API はプログラムが呼び出すために作られています。

SpicyAPI では： API は、すべてのツールがモデルにたどり着くための経路です。プレイグラウンド、CLI、MCP サーバー、SDK はどれも、あなた自身のコードが送れるのと同じ種類のリクエストを api.spicyapi.ai に送っています。

詳しくは： OpenAPI とエンドポイント一覧

API キー（API key）

リクエストがあなたから送られたものだと証明する、秘密の文字列です。プログラムが使うパスワードだと思って扱ってください。

SpicyAPI では： キーは sk-spicy- で始まり、コンソールの API キーページで作成します。キーは一度しか表示されません。なくした場合は新しく作成してください。リクエストのたびに、キーを Authorization: Bearer ヘッダーに入れて送ります。キーは自分のパソコンかサーバーだけに置き、Web ページ、モバイルアプリ、公開リポジトリ、スクリーンショット、チャットには絶対に載せないでください。キーごとに、専用の利用上限、呼び出しを許可するモデルの一覧、接続を許可する IP アドレスの一覧を設定できます。

詳しくは： 認証 · アカウントの準備

アセットと出力 URL（Asset and output URL）

アセットとは、タスクが作った 1 つひとつのファイル（画像や動画など）のことです。出力 URL は、そのファイルをダウンロードするための Web アドレスです。

SpicyAPI では： 完了したタスクは、作ったファイルを output.assets[] に並べて返します。それぞれに、API キーなしで直接ダウンロードできる url と、expiresAt、mime（ファイルの種類）、サイズの情報が付いています。リンクの有効期間は約 20 分です。タスクをもう一度照会すると、新しいリンクが得られます。ファイル自体の保存期間は最長で約 14 日なので、必要なものはコピーを保存してください。pending: true が付いたアセットはまだ保存処理中です（数秒後にもう一度試してください）。unavailable: true が付いたアセットは完全に失われています。

詳しくは： 非同期タスク · メディア

残高（Balance）

生成の支払いに使う、アカウントに入っているお金です。

SpicyAPI では： 米ドル建ての前払い残高です。クレジットやポイントではありません。入金した分に有効期限はなく、特典残高にはそれぞれ有効期限があります。チャージはコンソールの請求ページで行います。GET /api/v1/chat/credit は、"128.42" のような文字列で 3 つの金額を返します。available（自由に使える額）、held（まだ実行中のタスクのために仮押さえされている額）、total（合計）です。アカウントによってはキャンペーンの付与残高や承認済みの後払い枠があり、それらは別の内訳として表示されます。無料枠はなく、新しいアカウントの残高は 0 から始まります。

詳しくは： 課金 · アカウントの準備

ベース URL（Base URL）

API が使うすべてのアドレスに共通する、固定の先頭部分です。コードやツールの設定に一度だけ書いておき、各リクエストはその後ろに自分のパスを付け足します。

SpicyAPI では： 2 種類あります。

ベース URL	用途
`https://api.spicyapi.ai/api/v1`	ネイティブ API：モデル、見積もり、タスク、アップロード、残高
`https://api.spicyapi.ai/v1`	OpenAI 形式（テキストと動画）と Anthropic 形式（テキスト）のエンドポイント

Google Gemini 形式のリクエストは https://api.spicyapi.ai/v1beta に送ります。Anthropic と Google GenAI の公式ライブラリはバージョン部分を自分で付け足すので、これらには https://api.spicyapi.ai だけを設定します。

詳しくは： クイックスタート · テキストとストリーミング

コールバック（Callback）

Webhook の別名です。SpicyAPI では、タスクを作成するときに callBackUrl フィールドでそのアドレスを渡します。

カタログ（Catalog）

提供されているモデルの一覧で、価格と、各モデルが受け付ける入力も載っています。

SpicyAPI では： 同じ一覧に 2 つの版があります。

公開カタログは、アカウントもキーも不要です。spicyapi.ai/explore に表示されている内容で、GET /console/v1/catalog/models が返すものでもあります。見て回ったり比べたりするのに使います。
認証付きカタログ（API キーを付けて呼び出す GET /api/v1/models）は、あなたのキーがいま呼び出せるモデルを、あなたのアカウントの価格で知るための、唯一信頼できる情報源です。有料の作業の前に、enabled と available がどちらも true の項目を選んでください。

CLI の spicyapi models list コマンド、SDK の listModels() メソッド、MCP の spicyapi_models_list ツールは、どれも認証付きカタログを読みます。

詳しくは： モデルカタログとスキーマ

CLI

command-line interface（コマンドライン・インターフェース）の略で、ボタンをクリックする代わりに、ターミナルでコマンドを入力して使うプログラムのことです。

SpicyAPI では： @spicyapi/cli として公開されている spicyapi コマンドを使うと、コードを書かずに、モデルの一覧表示、価格の確認、画像や動画のタスク作成、完了の待機、結果のダウンロードができます。お金がかかるのは tasks create と tasks retry だけで、どちらも先に確認を求めます。Node.js 22.13 以降が必要です。インストールせずに npx @spicyapi/cli で実行することもできます。

詳しくは： コマンドラインツール（CLI）

エンドポイント（Endpoint）

API が受け付ける、特定の 1 種類のリクエストです。HTTP メソッド（読み取りの GET、送信の POST など）とパスで呼び分けます。

SpicyAPI では： たとえば、POST /api/v1/jobs/createTask は生成を開始し、GET /api/v1/jobs/recordInfo はタスクを読み取ります。完全なアドレスは、ベース URL の後ろにパスを続けたものです。

詳しくは： OpenAPI とエンドポイント一覧

エンベロープ（Envelope）

すべての応答を包む、決まった形の外枠です。プログラムがどこを見ればよいかを、常にわかるようにするためのものです。

SpicyAPI では： ネイティブ API（/api/v1 配下）の応答は次のような形です。

{ "code": 200, "msg": "success", "data": {}, "request_id": "req_01k3m8x9q2z4v7n5p6r8s0t1w2" }

code は業務コード（200 は成功）、msg は人が読むためのメッセージです。data には応答の中身が入り、失敗したときは data 自体が省かれます。request_id はこのリクエストを識別する ID です。OpenAI・Anthropic・Gemini 互換のエンドポイントは、この形ではなく、それぞれのプロトコル自身の形式で返します。

詳しくは： エラー

環境変数（Environment variable）

ターミナルが、起動するすべてのプログラムに渡す、名前付きの値です。秘密のキーのような設定値を、ファイルやコマンドに書き込まずにプログラムに読ませることができます。

SpicyAPI では： SDK、CLI、MCP サーバー、そしてこのドキュメントのコード例は、SPICY_API_KEY という名前の変数から API キーを読み取ります。いま開いているターミナルのウィンドウで設定するには、次のようにします。

export SPICY_API_KEY="sk-spicy-paste-your-key-here"

この設定は、ウィンドウを閉じると消えます。ずっと有効にする方法と、キー全体を表示せずに確認する方法は、CLI のページで説明しています。

詳しくは： CLI：始める前に · アカウントの準備

エラーコード（Error code）

何がうまくいかなかったかをプログラムに伝える、短い決まった値です。これがあれば、プログラムはメッセージの文章を読まずに対応を決められます。

SpicyAPI では： 2 種類あります。

エンベロープの code は、リクエストそのものについての結果です。200 は成功で、ほかに 400（不正なリクエスト）、401（キーの問題）、40201（残高不足）、40202（利用上限に到達）、429（リクエストが多すぎる）などがあります。これは業務コードで、一緒に送られる HTTP ステータスよりも具体的です。
errorCode は、受理されたあとで失敗したタスクに付きます。値は次の 9 つのいずれかです：invalid_request、unsupported_combination、content_rejected、rate_limited、upstream_unavailable、generation_failed、timeout、invalid_asset、upstream_failed。

対応するメッセージである msg と errorMessage は、人が読むためのものです。言い回しは変わることがあり、選んだ言語で返ってくることもあります。プログラムの分岐には、コードだけを使ってください。

詳しくは： エラー

仮押さえ・精算・解放（Hold, settle and release）

タスクの支払いの 3 つの段階です。仮押さえとは、確保されてはいるものの、まだ使われてはいないお金のことです。ホテルがカードに一定額を仮押さえするのと同じようなものです。

SpicyAPI では：

仮押さえ： タスクが受理されると、見積額（estimatedCost）が残高から確保され、held として表示されます。この時点ではまだ課金ではなく、同時に、このタスクにかかりうる最大額でもあります。
精算： タスクが成功すると、実際に使った分が課金され、その額が仮押さえ額を超えることはありません。余った分は利用可能残高に戻ります。タスクに settled: true が付いていれば、cost の金額は確定しています。
解放： 失敗・期限切れのタスクでは通常、仮押さえ額が全額解放されます。ただし、モデルページに明記された一部のコンテンツ拒否は、受理時の見積額で課金されます。最終請求額は settled と cost で確認してください。

詳しくは： 課金

HTTP ステータス（HTTP status）

すべての Web の応答の先頭に付く 3 桁の数字で、リクエストがおおまかにどうなったかを表します。2xx はうまくいったこと、4xx はリクエストの側に何か問題があったこと、5xx はサーバー側に問題があったことを意味します。

SpicyAPI では： タスクを作成すると 202 Accepted が返ります。これはタスクが受理されたという意味で、完了したという意味ではありません。ネイティブ API の応答には、より具体的な業務 code も付いています。たとえば残高不足は、HTTP 402 で code が 40201 です。コードで分岐するときはどちらか一方を選び、それを使い続けてください。

詳しくは： エラー

冪等キー（Idempotency key）

1 つの作業に対して自分で決めるラベルで、同じリクエストを 2 回送っても、作業が 1 回だけ行われるようにするためのものです。冪等（idempotent）とは、同じことをもう一度行っても、それ以上の効果が生じないことを意味します。

SpicyAPI では： タスクを作成または再試行するときに、Idempotency-Key ヘッダーに入れて送ります。値はたとえば order-8814-render-1 のようにします。通信が切れてタスクが始まったかどうかわからない場合は、24 時間以内に、同じリクエストを同じキーと同じ API キーで送り直してください。元のタスクが返ってきて、二重に課金されることはありません。新しい作業には、毎回新しいキーを使います。同じキーを別のリクエストに使い回すと、409 で拒否されます。キーは最大 128 文字です。

詳しくは： 冪等性

入力スキーマ（Input schema）

リクエストにどのフィールドを入れてよいか、それぞれの型は何か、どんな値が許されるかを、機械が読める形で記述したものです。

SpicyAPI では： モデルごとに、JSON Schema で書かれた inputSchema があります。input に入れられるフィールド（prompt、image_url、duration_seconds など）が、その制限と既定値とともに並んでいます。サーバーはすべてのリクエストをこれに照らして検証し、未知のフィールドが 1 つでもあれば 400 エラーになります。プレイグラウンドのフォームも同じスキーマから作られており、カタログの examples は、このスキーマの検証をすでに通過した完全な入力例です。

詳しくは： モデルカタログとスキーマ · Spicy Schema

JSON

構造を持ったデータを表すためのテキスト形式で、波かっこの中に名前と値を並べて書きます。どのプログラミング言語でも読めるため、ほとんどの API で使われています。

SpicyAPI では： リクエストも応答も JSON です。最小限のタスクリクエストは次のようになります。

{ "model": "MODEL_ID_FROM_CATALOG", "input": { "prompt": "A paper lantern on a rainy street at night" } }

MODEL_ID_FROM_CATALOG は、ライブカタログから取得した実際のモデル ID の代わりに置いている仮の値です。金額は常に "0.008" のような文字列で送られるため、誤って丸められることはありません。

詳しくは： クイックスタート

MCP

Model Context Protocol の略です。MCP サーバーと呼ばれる小さなプログラムから、ツールと呼ばれる追加機能を AI アシスタントが読み込めるようにする、オープンな標準規格です。

SpicyAPI では： 公式サーバー @spicyapi/mcp は自分のパソコン上で動き、Claude、Cursor、VS Code、Codex などのアシスタントに 15 個の SpicyAPI ツールを提供します。モデルの閲覧、見積もりの取得、タスクの作成、ファイルのアップロード、結果の取得ができます。タスクの開始・再試行・破棄では処理が止まり、あなたに確認を求めます。価格がある操作では、その価格も表示されます。アシスタントが代わりに答えることはできません。Node.js 22.13 以降が必要です。

詳しくは： MCP サーバー

モダリティ（Modality）

モデルが扱うメディアの種類です。

SpicyAPI では： カタログの各項目には、image、video、text などの modality と、text-to-image や image-to-video などの tasks の一覧があります。これらを使ってカタログを絞り込めます。たとえば GET /api/v1/models?modality=video&task=image-to-video のように指定します。

詳しくは： モデルカタログとスキーマ

モデル ID（Model ID）

モデルを選ぶために送る、正確な名前です。

SpicyAPI では： ID は publisher/model/task の形をしています。モデルを作った開発元、どのモデルのどのバージョンか、そしてそのエンドポイントが何をするかを表します。画像編集のエンドポイントは edit で終わります。ID は必ずライブカタログ（GET /api/v1/models、spicyapi models list、listModels()）からコピーし、記憶や Web ページから写さないでください。モデルは追加・一時停止・終了されるからです。このドキュメントの例では、実際の ID が入る場所に MODEL_ID_FROM_CATALOG と書いています。この仮の値をそのまま送ると失敗します。

詳しくは： モデルカタログとスキーマ

Node.js

Web ブラウザーの外で JavaScript を動かすための無料のプログラムです。開発者向けツールの多くは JavaScript で書かれていて、動かすには Node.js のインストールが必要です。

SpicyAPI では： SDK、CLI、MCP サーバーには Node.js 22.13 以降が必要です。Skill が使うインストーラーは 22.20 以降を求めます。nodejs.org から LTS 版をインストールし、ターミナルで node --version を実行して確認してください。プレイグラウンドを使うだけの場合や、別の言語から API を呼び出す場合は、Node.js は必要ありません。

詳しくは： CLI：始める前に

npm と npx

npm は Node.js に付属するパッケージマネージャーで、JavaScript のパッケージをダウンロードしてインストールします。同じく付属する npx は、パッケージを恒久的にはインストールせずに実行します。

SpicyAPI では： Node.js 向けの 4 つのツールは、どれも npm パッケージです：@spicyapi/sdk、@spicyapi/cli、@spicyapi/mcp、@spicyapi/skill。たとえば npm install @spicyapi/sdk でプロジェクトに TypeScript SDK を追加でき、npx @spicyapi/cli status なら CLI をインストールせずに 1 回だけ実行できます。Python、Go、PHP、Java の SDK は、代わりにそれぞれの言語のツールでインストールします。各 SDK のページを参照してください。

詳しくは： TypeScript SDK · コマンドラインツール（CLI）

OpenAI 互換（OpenAI-compatible）

OpenAI の API と同じ形式でリクエストを受け付けることです。OpenAI 向けに書かれたソフトウェアが、アドレスとキーを変えるだけで動くようになります。

SpicyAPI では： テキストモデルは、OpenAI 形式の POST /v1/chat/completions と POST /v1/responses、Anthropic 形式の POST /v1/messages、Google Gemini 形式の /v1beta/models/… から、すべて同じ API キーで呼び出せます。公式の openai ライブラリは https://api.spicyapi.ai/v1 に向けてください。どのテキストモデルも、これらのどの形式でも使えます。これらのエンドポイントはリクエストが受理された時点の価格で課金し、見積もりを受け付けないので、キーに利用上限を設定しておいてください。

詳しくは： テキストとストリーミング

プレイグラウンド（Playground）

Web サイト上のフォームで、項目を埋めてボタンを押すだけで、コードを書かずにモデルを試せるものです。

SpicyAPI では： spicyapi.ai のすべてのモデルページにプレイグラウンドタブがあります。アカウントがなくても、フォームに入力して、そこから組み立てられるリクエストを確認できます。実行するにはログインと残高が必要です。実行のたびに先に見積額が表示され、API 呼び出しと同じように課金され、コンソールのログに表示されます。

詳しくは： SpicyAPI のしくみ

ポーリング（Polling）

知らせてもらうのを待つのではなく、何かが終わったかどうかをサーバーに何度も問い合わせることです。

SpicyAPI では： GET /api/v1/jobs/recordInfo?taskId=… で、状態が queued でも running でもなくなるまでタスクをポーリングします。最初の確認までに 2〜3 秒待ち、待ち時間を毎回約 1.5 倍ずつ延ばして 10〜15 秒で頭打ちにし、自分で決めた締め切りが来たら待つのをやめてください。待つのをやめても、タスクは止まりません。ポーリングはレート制限の対象になるので、本番環境では Webhook を優先してください。

詳しくは： 非同期タスク

破棄（Purge）

保存されている内容を、期限切れを待たずに、依頼に応じて完全に削除することです。

SpicyAPI では： POST /api/v1/jobs/purge（またはコンソールのログにある生成結果を破棄、spicyapi tasks purge、purgeTask()）は、終了したタスクが生成したファイル、その結果、入力に含まれるプロンプトの本文を削除します。課金の記録（金額、モデル、状態、タイムスタンプ、request_id）は残ります。破棄はキャンセルではなく、返金も一切ありません。また、元に戻すこともできません。使えるのは、終了したタスクに対してだけです。

詳しくは： データ保存と破棄

見積もり（Quote）

1 つの具体的なリクエストについて、事前に計算した価格です。

SpicyAPI では： POST /api/v1/jobs/quote は、送信するのと同じ本文を受け取り、タスクを作ることもお金を仮押さえすることもなく、estimatedCost、maxCharge、expiresAt を返します。無料で、有効期間は 5 分です。返ってきた quoteId と expectedCost を付けて送信したとき、リクエストや価格が変わっていれば、別の金額で課金されるのではなく、40901 で拒否されます。CLI と MCP サーバーは、タスクを作成する前に自動で見積もりを取ります。

詳しくは： 見積もりとプロトコル互換

レート制限（Rate limit）

一定の時間内に送れるリクエスト数の上限です。暴走した 1 つのプログラムが、サービスに過剰な負荷をかけないようにするためのものです。

SpicyAPI では： ネイティブ API の既定の上限は、アカウントごとに 10 秒あたり 1,000 リクエストです。読み取りと書き込みはそれぞれ別にこの上限を持ち、どちらもアカウントのすべてのキーで共有されます。ポーリングは読み取りとして数えるため、ポーリングが続いてもタスクの送信が止まることはありません。超えると 429 が返り、何秒待てばよいかが Retry-After ヘッダーで示されます。数えるのはリクエストで、タスクではありません。すでに実行中のタスクがこの上限を消費することはありません。

詳しくは： レート制限

request_id

サーバーが 1 つのリクエストに付ける識別子で、ログからそのリクエストをあとで探し出せるようにするためのものです。

SpicyAPI では： ネイティブ API の応答には、成功でも失敗でも必ず request_id（たとえば req_01k3…）が付いており、X-Request-Id ヘッダーでも送られます。自分のログに残しておき、サポートに問い合わせるときに伝えてください。バージョン 2 の Webhook では、request_id はその配信を識別する値（whd_…）になり、配信が再試行されても変わりません。

詳しくは： エラー · Webhook

保存期間（Retention）

保存されたデータが削除されるまでの期間です。

SpicyAPI では：

対象	保存期間
結果のダウンロードリンク	約 20 分。もう一度照会すれば新しいリンクが得られます
生成された画像と動画	最長で約 14 日
入力としてアップロードしたファイル	1 日
プロンプトの本文とその他のタスクの内容	30 日
タスクの記録（ID、モデル、状態、金額、時刻）	内容を含まない形で保存されます

生成されたファイル、アップロードしたファイル、プロンプトの本文の保存期間は、コンソールのデータ保護ページで、または 1 件のタスクごとに X-Spicy-Retention ヘッダーで短くできます。破棄を使えば、いつでも内容を削除できます。どんな設定をしても、期間が長くなることはありません。

詳しくは： データ保存と破棄

SDK

software development kit（ソフトウェア開発キット）の略で、自分のプログラムに組み込んで使う、出来合いのコードライブラリです。これを使えば、リクエストを 1 つひとつ手で組み立てる必要がなくなります。

SpicyAPI では： 公式 SDK は 5 つあります。Node.js 上の TypeScript と JavaScript 向けの @spicyapi/sdk に加えて、Python、Go、PHP、Java 向けが 1 つずつです。どれもキーの扱い、タスクの待機、再試行、アップロード、Webhook の検証を引き受けるので、2、3 回の呼び出しで、送信から結果の取得までタスクを進められます。いずれも動くのはサーバー上だけで、ブラウザーやモバイルアプリでは使えません。また、どれもチャットモデルには対応していません。

詳しくは： TypeScript SDK · Python SDK · Go SDK · PHP SDK · Java SDK

署名・HMAC（Signature）

メッセージと、送り手と受け手が共有する秘密の値から計算するコードです。受け手はこれを使って、メッセージが本物で、途中で書き換えられていないことを確認できます。HMAC は、このコードを計算するための標準的な方式です。

SpicyAPI では： Webhook の配信にはすべて X-Webhook-Signature ヘッダーが付いています。これは、タスク ID、配信時刻、本文そのもののダイジェストに対して、あなたの Webhook 署名キーで計算した HMAC-SHA256 です。このキーはコンソールの Webhook ページで発行またはローテーション（再発行）し、表示されるのはそのときだけです。コピーしていなかった場合は、同じページでローテーションしてください。配信を信用する前に、SDK の verifyWebhook か spicyapi webhooks verify で署名を確認し、タイムスタンプが現在時刻から 5 分を超えてずれている配信は拒否してください。

詳しくは： Webhook

利用上限（Spend cap）

あらかじめ決めておく支出の上限です。ミスやキーの漏えいがあっても、残高をすべて使い切られないようにするためのものです。

SpicyAPI では： API キーごとに、米ドル建てで日次・月次・累計の上限を自分で設定でき、新しいキーには追加するまで上限が付きません。チームは日次と月次の予算を追加でき、プラットフォーム自体にも 1 日あたりの上限があります。どれか 1 つでも超えることになるタスクは、開始前に 40202 で拒否され、何も課金されません。日次上限は 00:00 UTC に、月次上限は毎月 1 日にリセットされ、累計上限はリセットされません。0 を入力すると、その段階では上限なしになります。

詳しくは： 課金 · 認証

ストリーミング・SSE（Streaming）

応答を最後にまとめて送るのではなく、1 本の開いた接続を通じて、できあがった部分から順に送ることです。SSE は server-sent events（サーバー送信イベント）の略で、そのためによく使われる Web の形式です。

SpicyAPI では： テキストモデルは、互換エンドポイント（たとえば /v1/chat/completions に stream: true を指定）またはネイティブの POST /api/v1/jobs/stream を通じて、返答を少しずつストリーミングできます。ストリームの終わりの示し方は、プロトコルごとに異なります。途中で接続を閉じるとテキストを受け取れなくなりますが、モデルは止まらず、使用量はそのまま課金されます。ストリーミングしたテキストは保存されないため、あとから取得し直すことはできません。

詳しくは： テキストとストリーミング

タスク（Task）

バックグラウンドで実行される 1 つの作業の単位です。作業を預けておき、結果はあとで受け取ります。

SpicyAPI では： 画像や動画の生成は、すべてタスクです。POST /api/v1/jobs/createTask がタスクを受理し、job_ で始まるタスク ID を返します。そのあとは、タスクをポーリングするか、完了時に Webhook を受け取ります。API からタスクを読み取れるのは、そのタスクを作成したのと同じ API キーだけです。コンソールのログページには、アカウントのすべてのタスクが表示されます。受理されたタスクはキャンセルできません。

詳しくは： 非同期タスク · タスク確定と再試行

タスクの状態（Task state）

タスクがいま、一生のどの段階にあるかを表すものです。

SpicyAPI では：

状態	意味	課金される？
`queued`	受理され、開始を待っている	金額は仮押さえ中で、まだ課金されない
`running`	モデルが処理している	金額は仮押さえ中で、まだ課金されない
`succeeded`	結果が出て完了した	実際の使用量で課金。仮押さえ額を超えることはない
`failed`	結果が出ないまま終わった。理由は `errorCode` でわかる	失敗・期限切れのタスクでは通常、仮押さえ額が全額解放されます。ただし、モデルページに明記された一部のコンテンツ拒否は、受理時の見積額で課金されます。最終請求額は `settled` と `cost` で確認してください。
`expired`	完了しないまま期限を過ぎた	されない。全額解放

古い記録には canceled と表示されることもありますが、新しいタスクがこの状態になることはありません。queued と running 以外の状態は、すべて終端状態として扱ってください。

詳しくは： 非同期タスク

ターミナル（Terminal）

コマンドを入力して Enter キーを押し、実行するための、文字だけのウィンドウです。macOS ではターミナルアプリ、Windows では PowerShell を使います。多くの Linux デスクトップでは Ctrl + Alt + T で開きます。英語ではどちらも terminal と呼ぶため紛らわしいのですが、終端状態（terminal state）とは別物です。

SpicyAPI では： ターミナルは、CLI を実行するとき、MCP サーバーや Skill などの Node.js ツールをインストールするとき、このドキュメントの curl の例を試すときに使います。

詳しくは： CLI：始める前に

終端状態（Terminal state）

最終的な状態のことです。タスクがいったんこの状態になると、そこから変わることはありません。

SpicyAPI では： queued と running 以外のタスクの状態は、すべて終端状態です。succeeded、failed、expired、そして古い記録にある canceled がこれにあたります。コードでは、最終的な状態を列挙するのではなく、「queued でも running でもない」かどうかで判定してください。そうすれば、新しい状態が追加されてもコードはそのまま動きます。Webhook が送られるのは、タスクが終端状態になったときだけです。破棄できるのは終了したタスクだけで、再試行できるのは failed か expired のタスクです。

詳しくは： 非同期タスク

アップロード（Upload）

自分のパソコンにあるファイルをサーバーへ送り、そこで使えるようにすることです。

SpicyAPI では： 画像・動画・音声の入力を受け付けるモデルには、3 つの方法でファイルを渡せます。ファイルを指す公開 HTTPS リンク、リクエストに data URI として埋め込んだ小さな画像（1 MiB まで）、アップロードしたファイルです。アップロードは 3 ステップで行います。チケットを発行し（POST /api/v1/common/upload-url）、チケットに書かれたアドレスへファイルを送り、確定します（POST /api/v1/files/{fileId}/commit）。確定すると spicy:// のアドレスが返るので、それをモデルの入力フィールドに入れます。このアドレスは 1 日使えます。画像は 10 MiB まで、音声と動画は 90 MiB かつ 600 秒までです。SDK の uploadFile()、spicyapi files upload、MCP サーバーは、この 3 ステップをすべて代わりに行います。

詳しくは： メディア

Webhook

何かが起きたときにほかのサービスから呼び出される、自分のサーバー上のアドレスです。これがあれば、何度も問い合わせる必要がなくなります。コールバックとも呼ばれます。

SpicyAPI では： タスクを作成するときに、公開された HTTPS のアドレスを callBackUrl に指定します。タスクが終端状態になると、SpicyAPI はそのアドレスに、recordInfo が返すのと同じ内容の POST リクエストを送ります。このリクエストには、あなたの Webhook 署名キーによる署名が付いています。15 秒以内に任意の 2xx ステータスで応答してください。そうしなかった場合、配信は再試行され、約 9 時間のあいだに最大 8 回まで試みられます。コンソールの Webhook ページから再送することもできます。タスクが開始しただけのときには、通知は届きません。http://localhost:3000 のようなローカルアドレスでは Webhook を受け取れないので、自分のパソコンで開発している間はポーリングを使ってください。

詳しくは： Webhook

ワークスペースとチーム（Workspace and team）

複数の人が 1 つのアカウントのもとで、同じキー、タスク、予算を使うための共有の場です。

SpicyAPI では： チームのワークスペースには、owner、admin、developer、billing、readonly のいずれかのロールを持つメンバーがいます。メンバーは全員、タスクの概要と利用量を見られます。owner、admin、developer は、タスクの入力と結果も見られます。チームの新しいタスクの費用はオーナーのアカウントが支払い、メンバーがオーナー個人の残高や支払いを見ることはありません。チームには日次と月次の予算を設定できます。

詳しくは： コンソールとチーム

このページの内容