チュートリアル

HiAPI のリクエスト失敗時になぜ課金されるのか？

Oct 8, 2026

問題の現象

生成タスクを POST で https://api.hiapi.ai/v1/tasks に送信し、その後 GET /v1/tasks/:id でポーリングしたところ、"status": "fail" と error オブジェクト（例：{"code": "TASK_FAILED", "message": "task failed"}）が返ってきたとします。このポーリング呼び出し自体の HTTP ステータスコードは正常な 200 です——HiAPI は失敗情報をステータスコードではなく JSON body の中に包んで返します。このタスクは実際に queued → handling を経てから失敗したため、今回の試行が通常の呼び出しと同じように課金されたと誤解しやすくなります。実際には、タスクが終態 fail に到達したことは課金されたことを意味しません——しかし、返金がまだ反映されていない段階で残高を確認すると、作成時のあの予約（プリオーソリゼーション）によって、帳簿上は課金されたように見えてしまいます。

よくある原因

「予約」を「課金」と勘違いしている。 HiAPI はタスクが作成された直後、まだ実際に実行が始まっていない時点で、そのタスクの推定費用を予約します。この予約は即座に残高に反映されます——しかし、それはまだ課金ではありません。
タスクの実行中に残高を確認している。 queued/handling から終態に至るまでの間、この予約は本来「保留中」の状態です。これは設計された動作です。終態（success または fail）になって初めて精算されます。
「下流が実際に実行されて失敗した」と「作成段階で拒否された」を混同している。 status: "fail"（例えば error.code: "TASK_FAILED"）に到達したタスクは、実際に作成され、実際に実行され、下流が失敗したものです——HiAPI のドキュメントでは、タスクがこの終態に到達すると予約金額が全額自動的に返金されることが明記されています。一方、taskId を一度も取得できなかったリクエスト——例えば同期的に返される 402 INSUFFICIENT_QUOTA——はタスクが存在する前に拒否されており、そもそも予約されたものは何もありません。両者は外から見るとどちらも「失敗」ですが、前者だけが実際に予約という仕組みに触れています。
Idempotency-Key の使い方が間違っている。 同じ key、同じリクエストボディでリプレイした場合、元の taskId が返るだけで、新しいタスクは作成されず、二重に課金されることもありません。しかし、同じ key でリクエストボディを変えてリプレイすると、作成段階で直接 422 IDEMPOTENCY_KEY_MISMATCH が返されます。同じ key で最初の呼び出しがまだ処理中のときに再度送信すると、409 IDEMPOTENCY_KEY_PROCESSING が返されます。これらの経路はいずれも課金可能なタスクを作成しません。

修正手順

GET /v1/tasks/:id をポーリングし、data.status を直接確認してください——ある時点の残高のスクリーンショットだけで課金結果を推測しないでください。queued、handling、archiving はすべて非終態です；終態は success と fail だけです。
data.status が "fail" であれば、それは返金される結果です。data.error.code（例えば TASK_FAILED）を確認して原因を把握し、その後もう一度残高を確認してください——返金はタスクがこの終態に到達した後に自動的に反映されます。
POST /v1/tasks の呼び出し自体が非 2xx ステータスコード（400/402/409/415/422）を返し、かつ body に taskId がない場合、返金すべきタスクはありません——そもそもタスクが作成されておらず、課金もされていないからです。残高不足の具体的なケースは、402 レスポンスの error_code: "INSUFFICIENT_QUOTA" として現れます。
HiAPI 請求管理画面で「予約—返金」の一対の取引記録を照合してください。ある時点の残高の数字だけを見ないでください。
失敗したタスクを再試行する際は、今回の本当に新しい試行に対して新しい Idempotency-Key を付与してください。古い key でリクエストボディを変えてリプレイしないでください（422 が発生します）。また、最初のリクエストがまだ処理中のときに同じ key で再度送信しないでください（409 が発生します）。
タスクがすでに fail 終態に到達していることを確認したのに、しばらく経っても予約金額が返金されない場合、これはこの自動返金の仕組みの範囲を超えています——自己回復するものと仮定せず、直接サポートに連絡してください。

最小検証例

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "model": "gpt-image-2/text-to-image",
    "input": { "prompt": "a minimalist desk setup, studio lighting" }
  }'

ここでは model フィールドにルーティングサフィックス /text-to-image が付いています。本文執筆時点では、HiAPI モデルインデックスにおいて gpt-image-2 グループにはルーティングサフィックス付きのエントリ（/text-to-image、/image-to-image）のみが収録されており、裸の id エントリはありません。サフィックスを付ける必要があるか、どのサフィックスを付けるかは、必ずこのリアルタイムのモデルインデックスで availability: "online" のエントリを基準にしてください。他のモデルや古いドキュメントの記述をそのままコピーしないでください。

返された taskId を取得したらポーリングします：

curl -s https://api.hiapi.ai/v1/tasks/$TASK_ID \
  -H "Authorization: Bearer $HIAPI_API_KEY"

返金された失敗タスクはこのようになります：

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "gpt-image-2/text-to-image",
    "status": "fail",
    "created": 1777282033,
    "completed": 1777282099,
    "error": { "code": "TASK_FAILED", "message": "task failed" }
  }
}

FAQ

画像や動画のタスクが失敗した場合、HiAPI は課金しますか？ いいえ。タスクが終態 fail に到達すると、作成時に予約された金額は全額自動的に返金されます。

タスクを送信した直後に残高が減ったのに、そのタスクが後で失敗しました。なぜ残高が戻らないのですか？ その減少は作成時の予約であり、課金ではありません。タスクが終態に到達した後に自動的に精算されます——fail なら返金され、success で初めて実際に消費されます。

402 エラーとタスク失敗の違いは何ですか？ 402 INSUFFICIENT_QUOTA はタスクがそもそも作成されていないことを意味するため、予約されるものも返金されるものもありません。一方、taskId を取得し、その後 status が "fail" になったタスクは、実際に作成され、実際に実行され、そして下流が失敗したものです；HiAPI はこの予約を自動的に返金します。

同じ Idempotency-Key で再試行すると、二重に課金されますか？ いいえ。同じ key、同じリクエストボディでリプレイした場合、元の taskId が返るだけで、新しいタスクは作成されません。同じ key でリクエストボディを変えた場合は、直接 422 IDEMPOTENCY_KEY_MISMATCH が返され、重複したタスクも作成されません。

予約と返金の記録はどこで確認できますか？ HiAPI 請求管理画面の請求および取引記録で確認できます。