コマンドラインツール（CLI）

CLI とは

spicyapi は、ターミナルで動かす小さなプログラムです。ターミナルとは、ボタンをクリックする代わりにコマンドを入力して操作するウィンドウのことです。1 つのコマンドが 1 つの仕事をします。アカウントで使えるモデルを一覧する、生成にいくらかかるかを教える、画像や動画の生成を開始する、完了を待って結果をダウンロードするためのリンクを渡す、といった仕事です。

コードは一切書きません。コマンドを入力して Enter キーを押し、返ってきた答えを読むだけです。

次のような場面に向いています。

• 誰かが組み込みのコードを書く前に、モデルを試して価格を比べたい
• 自分のパソコンから画像や動画を生成して、ファイルを保存したい
• 同じ種類の生成を、毎回ページをクリックして回らずに繰り返したい
• 何かを組み立てる前に、モデルの正確な設定項目を確かめたい

CLI が扱うのは画像と動画の生成です。テキストモデルやチャットモデルは、テキストとストリーミングで説明しているチャット互換のエンドポイントから呼び出します。

公式ツールはほかに 3 つあります。コマンドを自分で入力したいなら、CLI を選んでください。

ほかの言語で書いているなら、Python、Go、PHP、Java の公式 SDK もあります。

できること

上のコマンドで <task-id> のように山かっこで囲んだ語は、「ここに自分の値を入れる」という意味です。山かっこは付けずに入力してください。

始める前に

必要なものは 4 つです。ターミナル、Node.js、API キー、そして CLI を実行する方法です。初めてなら 10 分ほどかかります。

node -v

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

nano ~/.zshrc

echo "${SPICY_API_KEY:0:9}"

npx @spicyapi/cli status

最初の結果を得る

ここでは画像を 1 枚生成して、ダウンロードするまでを順に進めます。各ステップで、コマンド、表示されるおおよその内容、そこで何が起きたかを示します。数値、ID、時刻は、実際に試したときとは異なります。

spicyapi status

SpicyAPI is reachable — api.spicyapi.ai answered in 523 ms.

spicyapi balance

available: 12.34
held: 0.06
total: 12.40

spicyapi models list --modality image --json

{
  "total": 1,
  "items": [
    {
      "model": "MODEL_ID_FROM_CATALOG",
      "displayName": "Example image model",
      "modality": "image",
      "tasks": ["text-to-image"],
      "enabled": true,
      "available": true,
      "pricing": [
        { "variant": "", "unit": "per_image", "price": "0.03", "currency": "USD" }
      ]
    }
  ]
}

spicyapi models get MODEL_ID_FROM_CATALOG --json

{
  "model": "MODEL_ID_FROM_CATALOG",
  "enabled": true,
  "available": true,
  "inputSchema": {
    "type": "object",
    "required": ["prompt"],
    "properties": {
      "prompt": { "type": "string" },
      "aspect_ratio": { "type": "string", "enum": ["1:1", "16:9", "9:16"] }
    },
    "additionalProperties": false
  }
}

cat > input.json <<'EOF'
{"prompt": "A paper lantern glowing on a rainy street at night, cinematic light"}
EOF

spicyapi tasks quote --model MODEL_ID_FROM_CATALOG --input-file input.json

quoteId: eyJ2IjoxLCJtIjoi…
model: MODEL_ID_FROM_CATALOG
estimatedCost: 0.03
maxCharge: 0.03
currency: USD
quantity: 1
unit: per_image
expiresAt: 2026-09-17T08:05:00Z

spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --wait

Estimated charge: USD 0.03; maximum charge: USD 0.03. Quote expires: 2026-09-17T08:05:00Z.
Idempotency-Key: 4f6755a5-0d72-4420-9f6b-9faf0e2b0241
Create a billable task with model MODEL_ID_FROM_CATALOG? Estimated charge: USD 0.03; maximum charge: USD 0.03. Quote expires: 2026-09-17T08:05:00Z. Idempotency-Key: 4f6755a5-0d72-4420-9f6b-9faf0e2b0241. Continue? [y/N]

Accepted: job_01k3m8x9q2z4v7n5p6r8s0t1w3
If waiting is interrupted: spicyapi tasks get job_01k3m8x9q2z4v7n5p6r8s0t1w3

idempotencyKey: 4f6755a5-0d72-4420-9f6b-9faf0e2b0241
accepted: {"taskId":"job_01k3m8x9q2z4v7n5p6r8s0t1w3","state":"queued","estimatedCost":"0.03","deadlineAt":"2026-09-17T08:30:00Z"}
task: {"taskId":"job_01k3m8x9q2z4v7n5p6r8s0t1w3","model":"MODEL_ID_FROM_CATALOG","state":"succeeded","output":{"assets":[{"key":"tasks/…/result.png","url":"https://…","expiresAt":"2026-09-17T08:20:00Z","mime":"image/png","width":1024,"height":1024}]},"cost":"0.03","settled":true,…}

curl -L -o result.png "PASTE_THE_URL_HERE"

出力の読み方

• 通常の出力は、1 行に 1 つずつ name: value の形で表示されます。output や retention のように複数の要素を含む値は、1 行の JSON として表示されます。
• --json は、完全な応答をインデント付きの JSON で表示します。どのコマンドでも使え、コマンド名の前にも後ろにも置けます。spicyapi --json balance と spicyapi balance --json は同じです。
• 結果は画面の通常出力に、メッセージはエラー出力に出ます。 価格、冪等キー、Accepted: の行、エラーはメッセージです。そのため、spicyapi --json tasks get <task-id> > task.json とすると task.json には結果だけが保存され、メッセージは画面に表示されたままになります。
• エラーは Error: <what went wrong> (request req_…) のような形で、たいていその下に、何をすればよいかを示す Next: 行が続きます。--json を付けた場合、エラーは error、type、status、code、requestId を含む 1 行の JSON オブジェクトになり、Next: 行はありません。キーが設定されていないときの type は MissingApiKeyError です。サポートに問い合わせるときは、req_… の値を伝えてください。
• 金額は、$ 記号の付かないプレーンテキストの米ドル金額です（例：0.03）。
• 時刻は UTC です。2026-09-17T08:05:00Z の末尾の Z は UTC を表します。
• 終了ステータスは、コマンドが成功すると 0、失敗すると 0 以外になります。スクリプトでこれを確認できます。

コマンドリファレンス

どのコマンドにもヘルプが組み込まれています。spicyapi tasks create --help のように --help を付けてください。

共通オプションと環境変数

次のオプションは、どのコマンドでも使えます。

status

内容： SpicyAPI が稼働していて、自分のパソコンから接続できるかを確認します。

spicyapi status

オプションはありません。キーは不要で、無料です。

出力： 1 文です。SpicyAPI is reachable — … answered in … ms. なら問題ありません。could not be reached は、パソコンに応答が返ってこなかったという意味なので、ネットワークやプロキシを確認してください。is not healthy や reports it is not ready は当社側の問題で、現在発生中の障害は status.spicyapi.ai に掲載されています。

--json を付けると、個々の確認結果がそのまま表示されます。大事なのは operational: true かどうかです。公開アドレスでは、readiness の項目がステータス 404 になっていても正常です。

docs search

内容： トピックに合うドキュメントのページを探します。CLI に組み込まれた小さな索引を検索するので、キーがなくても、SpicyAPI を呼び出さなくても動きます。各結果には、このドキュメントサイト docs.spicyapi.ai のページへのリンクが付いています。

spicyapi docs search [words] [--limit <count>]

spicyapi docs search retention

slug: retention
title: Retention and destruction
summary: What the platform caps are, how far down you can dial them, how to destroy a task's content, and what we cannot promise.
keywords: ["privacy","delete","storage","retention","per-request retention","purge","destroy"]
url: https://docs.spicyapi.ai/docs/retention

結果が複数ある場合は続けて表示され、それぞれが slug: で始まります。一致するものがない場合はそう表示され、それでも終了ステータスは 0 になります。

No documentation matched "refnd". Try fewer or different words, or run `spicyapi docs search` without words to browse pages.

--json を付けると、一致なしのときは空の一覧 [] が表示されます。無料です。

models list

内容： あなたのアカウントでいま呼び出せるモデルを、あなたのアカウントに適用される価格とあわせて一覧します。

spicyapi models list [options]

spicyapi models list --modality video --task image-to-video --json

出力： total と items です。--json を付けないとすべての項目が 1 行に表示されるので、付けて実行してください。各項目で特に役立つフィールドは次のとおりです。

無料です。モデル一覧の取得もアカウントのリクエストレートに数えられるので、生成のたびに実行する必要はありません。

models get

内容： 1 つのモデルの情報を、受け付ける設定も含めてすべて表示します。

spicyapi models get <model>

spicyapi models get MODEL_ID_FROM_CATALOG --json

出力： models list と同じフィールドに、inputSchema が加わります。inputSchema では、required（必ず送る設定）、properties（使えるすべての設定とその型）、enum（使える値の一覧）、minimum と maximum（数値の範囲）、default（設定を省略したときに使われる値）を読んでください。x-ui という名前の項目はフォームを組み立てるためのヒントなので、無視してかまいません。無料です。

balance

内容： アカウントで使える金額を表示します。

spicyapi balance

オプションはありません。無料です。

出力： available（いま使える額）、held（まだ実行中のタスクのために仮押さえされている額）、total で、すべて米ドルです。funding が含まれることもあります。これは残高を前払いの資金とキャンペーンの付与残高に分けたもので、付与残高の有効期限や、どのモデルの支払いに使えるかも示します。生成のたびに残高を確認する必要はありません。tasks create が代わりに確認します。

usage

内容： いま使っている API キーで実行した生成の件数と費用を、日別・モデル別にまとめて表示します。

spicyapi usage [--from <date>] [--to <date>]

spicyapi usage --from 2026-09-01 --to 2026-10-01

これで 9 月がまるごと対象になります。--to は、集計に含まれない最初の日です。両方のオプションを省略すると、今日を含む直近 7 日間が表示されます。

出力： from、to、currency、totalCalls、totalSpend に続いて、days（日ごとの calls、succeeded、failed、spend）と models（同じ数値をモデルごとにまとめたもの）が表示されます。totalSpend に数えられるのは確定した請求額だけです。days と models は同じタスクを 2 通りに集計したものなので、足し合わせないでください。1 つのキーではなくアカウント全体の数値は、コンソールの利用量ページで確認してください。

無料です。1 分あたり 30 回までに制限されているので、合計の確認に使い、ループの中では呼び出さないでください。

tasks quote

内容： 1 回の生成にかかる正確な金額を、生成を開始することも、お金を仮押さえすることもなく教えてくれます。

spicyapi tasks quote --model <model> --input-file <path>

出力： quoteId、model、estimatedCost、maxCharge、currency、quantity（課金対象の秒数など）、unit、expiresAt です。見積もりの有効期間は 5 分です。

無料で、確認も求められません。モデルや設定を比べるときに使ってください。tasks create は自分で見積もりを取るので、その前にこのコマンドを実行する必要はありません。

tasks create

内容： 画像や動画の生成を開始します。お金がかかります。 CLI は必ず先に価格を表示して、確認を求めます。

spicyapi tasks create --model <model> --input-file <path> [options]

実行の流れ：

1. CLI が入力を読み取り、JSON オブジェクトであることを確認します。入力が指定されていなければ、ここで止まります。
2. スクリプトの中など、質問に答える人がいない状況で --yes が指定されていなければ、ここで止まります。
3. 見積もりを取り、見積額、最大請求額、見積もりの有効期限、冪等キーを表示します。
4. Continue? [y/N] と尋ねます。先に進むのは y か yes と答えた場合だけです。既定の答えはいいえです。
5. 見積もりどおりの価格でタスクを作成します。見積額が残高から仮押さえされ、その金額がタスクにかかりうる最大額にもなります。
6. --wait がなければ、idempotencyKey、taskId、state（queued）、estimatedCost、deadlineAt を表示して戻ります。--wait があれば、すぐに Accepted: <task-id> と再開用のコマンドを表示してから待機し、終わったら idempotencyKey、accepted、完了した task を表示します。

deadlineAt は、タスクが expired で終わらずに完了できる最も遅い時刻です。ダウンロードリンクやファイルの有効期限ではありません。

spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --wait

macOS と Linux では、入力をコマンドの中に直接書くこともできます。

spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-json '{"prompt": "A paper lantern on a rainy street"}'

（Ctrl + C ではなく）エラーで待機が失敗した場合は、必要な情報が最後の数行にまとめて繰り返されるので、Accepted: の行までさかのぼる必要はありません。

Error: task job_01k3m8x9q2z4v7n5p6r8s0t1w3 did not reach a terminal state within 600000ms
Task job_01k3m8x9q2z4v7n5p6r8s0t1w3 was accepted and may still be running; only the wait stopped.
Recover: spicyapi tasks get job_01k3m8x9q2z4v7n5p6r8s0t1w3
To replay the same request without creating a second task, reuse --idempotency-key 4f6755a5-0d72-4420-9f6b-9faf0e2b0241.

429 やサーバーエラーのように対処法がわかっているエラーの場合は、続けて Next: 行が表示されます。--json を付けた場合は、同じ情報がエラーオブジェクトの taskId、idempotencyKey、recover に入っています。

tasks wait

内容： すでに開始したタスクが終わるまで待ちます。

spicyapi tasks wait <task-id> [options]

spicyapi tasks wait job_01k3m8x9q2z4v7n5p6r8s0t1w3 --wait-timeout-ms 1800000

出力： 状態が succeeded、failed、expired のいずれかになると、完了したタスクを tasks get と同じフィールドで表示します。タスクが成功していてもファイルのコピーがまだ終わっていない場合は、もう少し待ち続けます。

時間切れになると、Error: task … did not reach a terminal state within 600000ms と表示されます。これは失敗ではなく、タスクはまだ実行中です。必要なら --wait-timeout-ms を長くして、もう一度待ってください。待機をやめても、タスクがキャンセルされることはありません。無料です。

tasks get

内容： 1 件のタスクの現在の様子を表示します。状態、費用、結果のリンク、内容が削除される時期です。

spicyapi tasks get <task-id>

タスクを作成したのと同じ API キーを使ってください。ほかのキーでは「見つからない」という結果になります。

出力のフィールド：

通常の出力の最後には、Outputs expire: … や Content: Destroyed — you removed the outputs … のような、わかりやすい言葉でのまとめが付きます。呼び出すたびに新しいダウンロードリンクが返ります。無料です。

tasks list

内容： いま使っている API キーで作成したタスクを、1 ページずつ一覧します。

spicyapi tasks list [options]

spicyapi --json tasks list --from 2026-09-01 --to 2026-09-08 --state failed

出力： items（それぞれに taskId、model、state、cost、settled、createdAt、deadlineAt、completedAt）、hasMore、nextCursor です。hasMore が true なら、--from と --to は変えずに、--cursor と nextCursor の値を付け加えて同じコマンドをもう一度実行します。一覧にはダウンロードリンクは含まれないので、目的のタスクに tasks get を使ってください。無料です。

tasks retry

内容： failed か expired のタスクを、新しい ID を持つ新しいタスクとしてもう一度実行します。お金がかかります。

spicyapi tasks retry <task-id> [options]

Retry source task … Continue? [y/N] と尋ねてきます。tasks create と違って、尋ねる前に価格は表示されません。 新しいタスクにはモデルの現在の価格で課金されるので、価格が気になる場合は、先に spicyapi models get <model> で確認してください。

出力： idempotencyKey、新しい taskId、sourceTaskId（元のタスク）、state、estimatedCost（仮押さえされた額）、deadlineAt です。

• 再試行できるのは failed と expired のタスク、それに古い canceled のタスクだけです。成功した結果の別バージョンがほしい場合は、tasks create を使ってください。
• 元の入力がそのまま使われるので、再試行が役立つのは、失敗の原因が一時的なものだった場合だけです。先に errorCode を確認してください。失敗したタスクを再試行するとエラーを参照してください。
• 入力がアップロード済みのファイルを指していて、そのファイルの期限がすでに切れている場合、再試行は失敗します。ファイルをもう一度アップロードして、tasks create を使ってください。
• 再試行では、元のタスクの保存期間の設定が引き継がれます。
• タスク ID が表示される前に tasks create の接続が切れた場合、それは失敗したタスクではありません。代わりに待機が中断されたタスクを再開するの復旧手順に従ってください。

tasks purge

内容： 終了したタスクの生成メディア、結果ペイロード（保存された結果データ）、プロンプト、その他の入力テキストを、期限切れを待たずにただちに完全削除します。

spicyapi tasks purge <task-id> [--yes]

まだ queued か running のタスクは破棄できません。キャンセルもできません（キャンセル用のコマンドも API もありません）。spicyapi tasks wait <task-id> で終わるのを待ってから破棄してください。

破棄は元に戻せないので、何が削除されるかを説明したうえで確認を求めます。残しておきたいものは、先にダウンロードしてください。

出力： taskId、contentState（purged）、purgedAt、contentRemovedBy（user）、billingRetained（常に true）、mediaDeletionPending に続いて、何を破棄したかと、保存されているメディアが 1 分ほどで削除されることを伝える 1 行が表示されます。contentState が present のままなら、今回は何も削除されていないので、あとでもう一度試してください。

無料ですが、返金ではありません。帳簿の記録、請求額、モデル、状態、タイムスタンプ、リクエスト ID は記録に残ります。データ保存と破棄を参照してください。

files upload

内容： 画像から動画を作るときの最初の画像など、パソコン上のファイルをアップロードし、入力に入れる spicy:// アドレスを返します。

spicyapi files upload <path> [--content-type <type>]

対応しているのは、10 MiB までの画像（.jpg、.jpeg、.png、.webp、.gif）と、90 MiB かつ 600 秒までの動画（.mp4、.webm）と音声（.mp3、.wav）です。モデルによっては、さらに低い上限を独自に設けています。

spicyapi files upload ./start-frame.jpg

fileId: fil_01k3m8x9q2z4v7n5p6r8s0t1w3
status: ready
bytes: 402118
contentType: image/jpeg
sha256: a91f4c2e5b7d16809e3f2a4c8d0b61e7c4a890e5d2f71b3c609ae8427d15f0c6
uri: spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3
expiresAt: 2026-09-18T09:12:11Z
width: 1280
height: 720

出力： uri の値を、表示されたとおり正確に、モデルのファイル用の設定（多くは image_url）にコピーします。使えるのは expiresAt まで、通常は 1 日です。それを過ぎたら、もう一度アップロードしてください。アップロードは無料です。

files download-url

内容： 終了したタスクの結果について、新しいダウンロードリンクを作ります。リンクを表示するだけで、ファイルは保存しません。

spicyapi files download-url <task-id> [--key <key>]

出力： key、url、expiresAt です。リンクは約 20 分有効で、ブラウザーで開くか curl でダウンロードします。まだ成功していないタスクでは「見つからない」という結果になります。ファイルをまだコピー中の場合は競合エラーになるので、数秒待ってからもう一度試してください。タスクのファイルが削除されたあとは、新しいリンクは作れません。無料です。

webhooks verify

内容： SpicyAPI のコールバックを受け取るサーバーを運用している場合（--callback-url を参照）、保存しておいたコールバック 1 件が本物で、改ざんされていないことを確認します。処理はすべて自分のパソコン上で行われ、API キーは要りません。

spicyapi webhooks verify --body-file <path> --timestamp <seconds> --signature <base64> --payload-version <version>

出力： 成功すると、payload（コールバックの内容）、payloadVersion、taskId、deliveryId（バージョン 2）、timestamp を表示します。一致しないものがあればエラーを表示し、0 以外の終了ステータスで終わります。無料です。

署名キーは登録時に自動で作成されますが、その値は一度も表示されません。コピーできるキーを得るには、コンソールで Webhook を開き、発行するをクリックします（すでに設定されている場合は再発行をクリックします）。新しいキーは一度しか表示されません。再発行はただちに反映され、新旧のキーを併用できる期間はありません。古いキーは、その時点で署名に使われなくなります。Webhook を参照してください。

よく使うレシピ

画像を生成する

spicyapi models list --modality image --json
spicyapi models get MODEL_ID_FROM_CATALOG --json
spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --wait

1 つ目のコマンドで ID を選び、2 つ目のコマンドで表示された設定をもとに input.json を作り、3 つ目を実行して y で確定します。各ステップの説明は最初の結果を得るにあります。

画像を動画にする

spicyapi models list --modality video --task image-to-video --json
spicyapi models get MODEL_ID_FROM_CATALOG --json

spicyapi files upload ./start-frame.jpg

{
  "prompt": "Slow push-in, rain running down the window",
  "image_url": "spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3",
  "duration_seconds": 5
}

spicyapi tasks quote --model MODEL_ID_FROM_CATALOG --input-file input.json
spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --wait --wait-timeout-ms 1800000

アップロードした画像は 1 日使えます。それを過ぎたら、もう一度アップロードしてください。

待機が中断されたタスクを再開する

ターミナルが閉じても、ネットワークが切れても、パソコンがスリープしても、待機が時間切れになっても、タスクは実行を続けます。タスクに戻る方法は、何が表示されていたかによって変わります。

• Accepted: job_… か、エラーの下の Recover: 行が表示されていた場合。 タスク ID がわかっています。もう一度待つか、状態を見るだけにします。

  spicyapi tasks wait job_01k3m8x9q2z4v7n5p6r8s0t1w3 --wait-timeout-ms 1800000
  spicyapi tasks get job_01k3m8x9q2z4v7n5p6r8s0t1w3

• Idempotency-Key: の行だけが表示されていた場合。 たとえば、タスクの作成中に接続が切れた場合です。モデルも入力も変えずに、同じコマンドにそのキーを付け加えてもう一度実行します。

  spicyapi tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --idempotency-key 4f6755a5-0d72-4420-9f6b-9faf0e2b0241 --wait

  CLI は価格を表示してもう一度確認を求めますが、最初の試行が受理されていた場合、SpicyAPI は 2 件目を開始して課金するのではなく、その同じタスクを返します。これは同じ API キーで 24 時間有効です。最初の試行が届いていなかった場合は、このときにタスクが 1 回だけ作成されます。

• どちらも表示されていなかった場合。 最近のタスクを一覧して、時刻とモデルから探します。

  spicyapi --json tasks list --limit 10

失敗したタスクを再試行する

まず、失敗した理由を調べます。

spicyapi tasks get job_01k3m8x9q2z4v7n5p6r8s0t1w3

次に errorCode を読みます。失敗・期限切れのタスクでは通常、仮押さえ額が全額解放されます。ただし、モデルページに明記された一部のコンテンツ拒否は、受理時の見積額で課金されます。最終請求額は settled と cost で確認してください。tasks retry は同じ入力をもう一度送るので、役立つのは原因が一時的だった場合だけです。

一覧はすべてエラーにあります。

再試行する意味がある場合は、実行します。新しいタスクが作成され、その分が課金されます。

spicyapi tasks retry job_01k3m8x9q2z4v7n5p6r8s0t1w3 --wait

利用状況を書き出す

いま使っているキーの 1 か月分の利用状況を、ファイルに保存します。

spicyapi --json usage --from 2026-09-01 --to 2026-10-01 > usage-2026-09.json

このファイルには、日別とモデル別の合計が入ります。タスクごとの一覧がほしい場合は、spicyapi --json tasks list --from 2026-09-01 --to 2026-09-08 --limit 100 を同じ方法で保存し、hasMore が true のあいだは nextCursor をたどって続きを取得します。アカウント全体の数値と請求書は、コンソールにあります。

スクリプトから CLI を実行する

スクリプトの中では誰も Continue? [y/N] に答えられないので、課金が発生するコマンドは --yes を付けない限り実行を拒否します。--yes を付けるときは、次の点を守ってください。

• 先に見積もりを取り、スクリプトの中で価格を確認する。
• poster-2026-09-17-v1 のように、生成ごとに固定の --idempotency-key を付けて、スクリプトを 2 回実行しても二重に課金されないようにする。
• --json を付けて、結果の state を読む。終了ステータスが 0 のコマンドでも、タスクが成功したとは限らない。
• コンソールで、キーに利用上限を設定する。

spicyapi --json tasks create --model MODEL_ID_FROM_CATALOG --input-file input.json --idempotency-key poster-2026-09-17-v1 --yes --wait > result.json

費用・確認・安全性

お金がかかるコマンド。 tasks create と tasks retry だけです。価格は米ドル建てです。見積もり、一覧、確認、アップロード、ダウンロード、削除は無料です。

先に価格を見る。 tasks quote は、何も開始せずにリクエストの価格を計算します。tasks create は自分で見積もりを取り、確認を求める前に Estimated charge と maximum charge を表示します。タスクが受理されると、見積額が仮押さえされ（held）、その金額が請求されうる最大額にもなります。タスクが成功すると、実際に生成された分だけを支払い、その金額を超えることはありません。余った分は残高に戻ります。

確認。 Continue? [y/N] は、y と入力しない限り答えがいいえになるという意味です。--yes はあなたの代わりに答えるので、価格がわかっている場合にだけ使ってください。スクリプトの中やパイプで入力を渡したときなど、質問できない環境で --yes がなければ、CLI は「はい」とみなさずに実行を拒否します。削除は元に戻せないので、tasks purge も同じように確認を求めます。tasks retry も確認を求めますが、先に価格は表示しません。

冪等キーをわかりやすく言うと。 注文番号のように、1 回の生成に付けるラベルです。tasks create と tasks retry は、実行のたびにこれを表示します。インターネット接続が切れて生成が始まったかどうかわからない場合は、同じコマンドに --idempotency-key と表示された値を付けてもう一度実行してください。元のタスクが返ってきて、二重に課金されることはありません。このラベルは、同じ API キーで 24 時間有効です。別の生成には使い回さないでください。同じキーで別の入力を送ると拒否されます。

キャンセルはできません。 受理されたタスクはキャンセルできません。Ctrl + C を押しても、ターミナルを閉じても、キーを失効させても、止まるのは待機だけです。タスクは最後まで実行され、通常どおり課金されます。

失敗・期限切れのタスクでは通常、仮押さえ額が全額解放されます。ただし、モデルページに明記された一部のコンテンツ拒否は、受理時の見積額で課金されます。最終請求額は settled と cost で確認してください。

残したいものはダウンロードする。 結果ファイルが保存されるのは最長で約 14 日（アカウントの設定や --retention でそれより短くしていればその期間）で、そのあとは完全に削除されます。ダウンロードリンクの有効期間は約 20 分ですが、ファイルが残っている間はいつでも新しいリンクを取得できます。アップロードしたファイルは 1 日使えます。プロンプトの本文は、既定では 30 日後に消去されます。課金の記録は残ります。データ保存と破棄を参照してください。

利用上限。 キーごとに、日次・月次・累計の上限を API キーページで設定できます。新しいキーには、設定するまで上限が付きません。上限を超えることになるタスクは、開始前に拒否されます。

キーの扱い。 CLI はキーを SPICY_API_KEY からしか読み取らず、表示することもありません。エラーのヒントに出すのも、先頭の 9 文字（sk-spicy-）までです。

詳しくは、課金、冪等性、タスク確定と再試行を参照してください。

トラブルシューティング

表示されたメッセージを探してください。SpicyAPI からのエラーは (request req_…) で終わります。サポートに問い合わせるときはこの値を伝えてください。ただし、キーは絶対に送らないでください。

すべてのエラーコードの説明はエラーに、復旧の手順はトラブルシューティングと復旧にあります。

ソースコード

このパッケージは MIT ライセンスで、github.com/spicyapi-ai/spicy-cli で公開のまま開発しています。このページで説明したコマンドの実装を読む、書かれている動作と食い違う点を報告する、変更を提案する——いずれもそこからどうぞ。

次のステップ