n8n

n8n は、ワークフロー自動化ツールです。SpicyAPI は、画像・動画・音声・チャットのモデルを、1 つの API と 1 つの前払い残高で n8n に提供します。つなぎ方は 3 通りあり、1 つのワークフローの中で組み合わせることもできます。

3 つとも、同じアカウント・キー・モデル・料金を使います。メディア生成では、ノードと HTTP Request テンプレートが送信前に料金を確認します。受理済みの同じメディア生成リクエストを元の Idempotency-Key で再送すると、既存のタスクが返ります。

画像ワークフローの出発点には、n8n の NSFW 画像ワークフローガイドをどうぞ。モデル選び、参考画像の編集、最初のポートレート、料金の例を紹介しています。お使いの n8n への接続手順は、この下で説明します。

始める前に

• API キー。 コンソールで作成します。キーは sk-spicy- で始まります。アカウントがまだない場合はアカウントの準備を参照してください。
• 残高。 最初の生成前に、コンソールの Billingで入金します。n8n ワークフロー、Studio、API は同じアカウント残高を使います。精算の仕組みは課金を参照してください。
• 自動化ごとに 1 つのキー。 ワークフローは、人がクリックするよりはるかに高い頻度で実行されることがあります。n8n 専用のキーを作成し、1 日または 1 か月の支出上限を設定して、ループ内のミスにも上限が働くようにしてください。認証を参照してください。
• n8n から api.spicyapi.ai に届くこと。 呼び出しを行うのは、ブラウザーではなく n8n サーバーです。

オプション 1: SpicyAPI コミュニティノード

このノードはオープンソース（MIT）で、github.com/spicyapi-ai/n8n-nodes-spicyapi で公開され、npm には @spicyapi/n8n-nodes-spicyapi として公開されています。実行時の依存関係はなく、通信するのは api.spicyapi.ai だけです。

名前の似た npm パッケージがほかにもありますが、無関係のサービスのものです。これは @spicyapi/n8n-nodes-spicyapi という名前のパッケージで、認証情報の名前は SpicyAPI (spicyapi.ai) API です。

インストール

cd ~/.n8n/nodes
npm install @spicyapi/n8n-nodes-spicyapi

オペレーション

画像・動画・音声を生成する

3 つの Generate オペレーションは、同じ欄を共有しています。

1. Model. 一覧から選びます。選択したリソースのモデルが開始価格付きで表示されます。モデル ID を手で入力することもできます。すべてのモデルとそのパラメーターは spicyapi.ai/models に載っています。
2. Prompt. モデルの主なテキスト入力です。音声読み上げモデルでは、読み上げるテキストになります。アップスケーラーなど、プロンプトのないモデルでは空のままにします。
3. Media Inputs. モデルが読み取る画像・動画・音声です。欄を選び（一覧には、選択したモデルのファイル入力が表示されます）、前のノードのバイナリフィールドか URL を使います。バイナリファイルは、SpicyAPI に自動でアップロードされます。参照画像のようなリスト形式の欄は、同じ欄に対して複数の入力を追加して埋めます。
4. Model Parameters. 選択したモデルのスキーマから生成されるフォームで、アスペクト比、解像度、長さ、シードなどがあります。空のままの欄は送信されず、モデルが自身の既定値を使います。
5. Additional Parameters (JSON). そのほかの入力フィールドを JSON オブジェクトで指定します。上記の欄より優先されます。

出力には、タスクレコード（taskId、state、cost、settled、output）が含まれます。Download Output がオン（既定）の場合は、ファイルが data、data_1 などにバイナリデータとしても添付されます。output.assets[].url のリンクは約 20 分で期限切れになりますが、バイナリのコピーは期限切れになりません。

n8n がバイナリデータをディスクに保存する設定でない場合、大きな動画はメモリ上に保持されます。セルフホストの n8n で動画を扱うときは、N8N_DEFAULT_BINARY_DATA_MODE=filesystem を設定してください。

コスト管理とリトライ

• すべてのアイテムは先に料金が見積もられます。 ノードは見積もりを取得します。見積もりが Max Cost per Item (USD)（既定 $2）を超える場合は、何かが作成される前にエラーで停止し、何も課金されません。上限をなくすには 0 に設定します。
• タスクは、見積もりの料金で作成されます。 見積もりから送信までの間に料金が変わった場合、ノードは再度見積もりを取得し、上限を再チェックして、再送信します。
• リトライしても二重課金されません。コスト上限とリトライを参照してください。

長時間かかるタスク

選択肢と、それぞれを使う場面については、長時間かかる動画タスクを参照してください。

オプション 2: HTTP Request テンプレート

インポートできるワークフローが 2 つあり、どちらも n8n 標準のノードだけを使うため、コミュニティノードなしで、セルフホストの n8n でも n8n Cloud でも動きます。ノードのリポジトリのサンプルフォルダーにあります。

画像テンプレートの構成

どのメディアモデルでも同じ手順が使えるので、このパターンを自分のワークフローにコピーできます。

リクエストとレスポンスの形式は、タスク、見積もりとプロトコル互換、メディアの入力と出力にあります。モデルが読み取るファイル（開始画像など）は、公開 URL か、アップロードした spicy:// ファイルを使えます。

オプション 3: AI Agent などの AI ノードでチャットモデルを使う

SpicyAPI のチャットエンドポイントは OpenAI 互換なので、n8n 標準の OpenAI ノードで使えます。これにはコミュニティノードは不要で、n8n Cloud でも動作します。

https://api.spicyapi.ai/v1

知っておくべき点です。

• モデル一覧には、画像・動画モデルも含まれます。 カスタムの Base URL では、n8n は /v1/models が返すものをすべて表示し、SpicyAPI の一覧にはすべてのモデルが入っています。/chat で終わるものを選ぶか、式モードで ID を入力してください。画像・動画モデルはチャットモデルではないため、エージェントでは失敗します。
• Use Responses API。 最近のバージョンの OpenAI Chat Model ノードは、/v1/chat/completions の代わりに /v1/responses へリクエストを送れます。SpicyAPI は /v1/responses に対応していますが、previous_response_id には対応していません。Responses API をオンにしてエージェントのリクエストが失敗する場合は、ノードで Use Responses API をオフにしてください。
• サンプリング設定。 モデルが宣言していないオプション（推論モデルの temperature など）を設定しても、SpicyAPI は失敗にせず無視し、無視した名前をレスポンスヘッダー X-Spicy-Ignored-Params に一覧で返します。モデルの範囲を超えた値は、受け付けられる最も近い値に変更され、X-Spicy-Adjusted-Params に一覧で返ります。宣言されていないそのほかのフィールドは、引き続き 400 になります。
• ツールと JSON 出力は、モデルによって異なります。/v1/models にあるモデルの supported_parameters を確認してください。
• 推論モデルは、推論トークンを max_tokens に含めて数えます。 20 のようにごく小さい値では、推論モデルが予算を思考だけで使い切り、テキストを返さないことがあります（upstream_failed:「the output budget was spent on reasoning」）。max_tokens を増やすか、reasoning_effort を下げてください。reasoning_effort の値は、モデルごとに異なります。
• ストリーミングと料金。 チャットは、呼び出しのあとにトークン数で課金されます。詳細はテキストとストリーミングのページに、リクエスト例はチャットのレシピにあります。

コスト上限とリトライ

支出の上限

• コンソールで、1 日または 1 か月の支出上限を付けた n8n 専用のキーを使い、ワークフローが少数のモデルしか必要としないなら、モデルの許可リストも設定してください。上限に達すると、呼び出しは 40202 で失敗し、その分は課金されません。
• メディアモデルでは、先に見積もりを取ってください。 ノードはこれを自動で行い、テンプレートは Get Quote と If のノードで行います。見積もりは、参照画像ごとの課金などの追加分を含む、そのリクエストの正確な料金です。そのため、見積もりに基づく料金チェックは信頼できますが、カタログの表に基づくものは信頼できません。
• 通常の失敗や期限切れのタスクでは、仮押さえ額が全額解放されます。一部のコンテンツ拒否は、モデルページに明記されている場合に限り課金されます。最終請求額は settled と cost で確認してください。課金も参照してください。

リトライしても二重課金されない理由

タスクを作成するすべての呼び出しには Idempotency-Key が付きます。同じリクエストで同じキーが再度届いた場合、SpicyAPI は 2 つ目を作成せず、すでに作成したタスクを返すため、保留も課金も 2 回目は起きません。これは n8n では重要です。ノードの Retry On Fail や、最初のリクエストが実は通っていたタイムアウトなど、何もしなくてもリクエストが 2 回送られることがあるからです。

• コミュニティノードは、実行、ノード、アイテム、その入力からキーを組み立てます。ノードのリトライでは、同じキーが再利用されます。新しい実行、入力の変更、ループの別の周回は新しい作業として扱われ、新しいキーが付きます。
• テンプレートは、実行 ID とアイテムのインデックスから、たとえば n8n-<execution id>-<item index> のようにキーを組み立てます。このパターンをループにコピーする場合は、キーにループのカウンターを加えてください。そうしないと、すべての周回が最初の周回のタスクを返してしまいます。
• $now のように試行のたびに変わるランダムな値は使わないでください。リトライのたびに新しい作業に見えてしまいます。

詳しくは冪等性を参照してください。

長時間かかる動画タスク

画像と音声のモデルは、通常 1 回のリクエストの中で終わります。動画は数分かかることがあります。その対処法は 3 つあり、n8n への負荷が最も軽いものから、順に並べると次のとおりです。

ノードが待つのをやめても、タスクは SpicyAPI 上で動き続け、成功すれば課金されます。あとで Task > Get で取得してください。再送信しないでください。コンソールの Logs でも確認できます。

結果は限られた期間だけ保持され、ダウンロードリンクは約 20 分で期限切れになります。それ以上の期間必要なら、ワークフローの中でファイルを、たとえばクラウドストレージに保存してください。保持期間を参照してください。

トラブルシューティング

SpicyAPI のエラーの末尾には、request_id またはタスク ID が付きます。サポートに連絡するときにそれを伝えれば、リクエストを正確に特定できます。エラーコードの意味はエラーで説明しており、より広いチェックリストはトラブルシューティングにあります。

モデルの利用には、SpicyAPI の利用規約と、お使いの n8n のエディションの規約が適用されます。