タスクの確定と再試行
受理された生成タスクをキャンセルできない理由と、失敗・期限切れタスクを安全に再試行する方法を説明します。
createTask が受理されると、生成タスクは確定し、キャンセルできません。queued でも running でも同じです。開始した生成を確実に停止できないため、作業と費用が継続するのに、キャンセルと表示するだけの操作を SpicyAPI は提供しません。
受理されたタスクは取り消せません
送信前にモデル、入力、見積額を確認してください。ブラウザーを閉じる、ページを離れる、API キーを削除する、といった操作では、受理済みタスクは止まりません。
終端タスクを再試行する
再試行は、成功せず終了したタスクを再び実行します。同じモデル、input、コールバック URL で新しいタスクを作り、元の本文を再送する必要はありません。新規タスクは通常と同じ課金です。受理時に見積額を予約し、成功した場合だけ課金します。
POST /api/v1/jobs/retrycurl -X POST https://api.spicyapi.ai/api/v1/jobs/retry \
-H "Authorization: Bearer $SPICY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: retry-order-8814-1" \
-d '{"taskId":"job_01k3m8x9q2z4v7n5p6r8s0t1w3"}'例の taskId を失敗タスクの ID へ置き換えます。retry には、retry-<sourceTaskId>-1 などの Idempotency-Key を必ず送ります。なければダブルクリックやネットワーク再試行で、課金対象が 2 件作られます。
再試行するのは failed と expired です。過去の canceled 記録は読み取り可能で、互換性のため再試行もできますが、新しいタスクはユーザー操作でその状態にはなりません。成功すると 新しい queued タスクを作り、HTTP 200（createTask の 202 ではありません）、code: 200 を返します。
{
"code": 200,
"msg": "success",
"data": {
"taskId": "job_01k3mnewtask",
"sourceTaskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
"state": "queued",
"estimatedCost": "0.08",
"deadlineAt": "2026-08-28T10:12:04Z"
},
"request_id": "req_01k3mretry"
}元ではなく新しい taskId をポーリングするか、完了を待ちます。非同期タスクを参照してください。
- 元のタスクは終端状態のまま変わりません。
- 新タスクの
sourceTaskIdが元を指し、再試行のつながりを残します。 - 現在のスキーマ、料金、権限、残高を再確認します。新規タスクとして再び待機列へ入り、元とは独立して処理されます。
- コールバック先は元と**同じ
callBackUrl**で、元の保持期間を引き継ぎます。retryのX-Spicy-Retentionは無視されます。 - 元の
inputをそのまま使います。小さい Base64 画像も含め、SpicyAPI のアップロードは 1 日保持されます。その後の再試行は400になるため、再アップロードしcreateTaskで新規作成します。 Idempotency-Keyの範囲は元タスクと再試行操作です。同じ元タスクへ同じキーを送ると、同じ新タスクを返し、追加作成しません。
再試行が拒否される場合
retry がエラーを返すと、予約も課金も行いません。
| 応答 | 理由 | 対処 |
|---|---|---|
404 | 元が存在しないか、別の API キーで作られた | 作成したキーを使う |
409 | 元が succeeded（別の生成には createTask が必要）、まだ queued・running、または精算未完了 | settled: true の failed・expired まで待つ。別の生成は createTask を使う |
409 | プロンプト保持期間の経過か内容の破棄により、元の入力がない | 元の要求を createTask で再送する |
400 | 参照アップロードが期限切れ、または保存したコールバック URL が現在の検証に通らない | 再アップロード、または有効な callBackUrl を使い、createTask で送る |
402 | 残高不足、または支出上限に到達 | 課金を参照 |
ネットワークエラーはタスク失敗ではありません
createTask の応答前に接続が切れた場合、元の Idempotency-Key で createTask を再送します。retry は、既存タスクの終端状態が確認できた場合だけ使います。
状態と再試行の対応
| 現在の状態 | できる操作 |
|---|---|
queued / running | 終端結果を待つ。キャンセルはできない |
succeeded | 結果の読み取り・ダウンロード。別の生成は新規タスク |
failed / expired | 別に課金される新規タスクとして再試行 |
過去の canceled | 読み取り・再試行。新しいユーザーキャンセル操作はない |
再試行前に errorCode を確認します。 rate_limited、upstream_unavailable、upstream_failed は再試行の価値があります。timeout と generation_failed は同じ失敗を繰り返す可能性があります。invalid_request、unsupported_combination、content_rejected は同じ入力でまた失敗し、invalid_asset は参照を再アップロードする必要があります。入力を変えて createTask を使ってください。タスク失敗コードを参照します。