HiAPI タスクが TASK_FAILED を返す：原因と修正方法

HiAPI のタスク API に非同期タスクを送信すると、送信成功時には HTTP 200 と taskId が返ります。タスクはその後バックグラウンドで実行され、ポーリングすると終端状態の fail で終わることがあります。このときポーリングの返却はおおよそ次のようになります——なお HTTP 呼び出し自体は依然として 200 である点に注意してください：

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M4RK...",
    "model": "seedream-5.0-lite/image-to-image",
    "status": "fail",
    "error": { "code": "TASK_FAILED", "message": "task failed" },
    "created": 1791827316,
    "completed": 1791827352,
    "storage": "temp"
  },
  "message": "success"
}

これが一般に言われる「TASK_FAILED エラー」です：リクエストは受け付けられ、タスクは実行され、最終的に成功しなかったということです。これは HTTP 4xx エラーではなく、タイムアウトでもありません。本記事ではこの返却を読み解き、各種原因を一つずつ修正する方法を解説します。

まず理解すべきこと：TASK_FAILED は HTTP ステータスコードではない

最も理解が必要な点：

• ポーリング呼び出しの HTTP ステータスコードは 200 で、返却ボディには "message": "success" とさえ書かれています——これは API 呼び出しが成功したことだけを示し、あなたのタスクが成功したことを示すものではありません。
• "status": "fail"（data 内）こそがタスク失敗を判断する根拠です。完了したタスクに対して、data.status は "success" または "fail" のみです。
• "TASK_FAILED" は data.error.code の値であり、status ではありません。一部の失敗ではより具体的な code とより有用な message が付きます（後述）。

したがって常に GET /v1/tasks/{taskId} をポーリングし、data.status を分岐の根拠にしてください。HTTP ステータスコードだけで成否を判断してはいけません。

タスク詳細から原因を特定する

終端状態の返却を受け取ったら、この順序で data フィールドを読みます：

1. まず data.status を見る——"fail" であればタスク失敗です。
2. 次に data.error.code を読む——これは機械判定可能なエラーカテゴリです（例：TASK_FAILED、INVALID_REQUEST、CONTENT_POLICY_VIOLATION）。
3. 最後に data.error.message を読む——これは人間向けの説明で、通常は原因を直接示します（例：ある入力 URL が取得できない）。

error.code は基本的に、この失敗が「リトライで解決できるかどうか」を決めます：汎用的な TASK_FAILED（message は多くが "task failed"）は多くの場合一時的な問題で、リトライ可能です。明確な code を伴うもの（例：INVALID_REQUEST、CONTENT_POLICY_VIOLATION）は確定的な失敗であり、入力を変えずに何度リトライしても同じ結果になります。

よくある終端 fail の原因

おおよそ出現頻度の高い順に並べています。

1. 入力画像 / 動画 URL にアクセスできない、または非公開ネットワーク

これは image-to-image、image/video-to-video タスクで最もよくある原因です。input がプラットフォームから取得できない URL を参照している場合、タスクは受け付けられますが実行時に失敗します。実際の終端状態の返却例：

"error": {
  "code": "INVALID_REQUEST",
  "message": "The image URL could not be downloaded. Please provide a reachable public HTTP(S) URL and try again."
}

ここでは message がすでに明確に説明しています。他のモデルでは同じ根本原因が汎用的な TASK_FAILED / "task failed" として現れることもあります。

修正： 入力を公衆からアクセス可能な HTTPS URL にホストし、送信前に検証します：

curl -I "https://your-host.example.com/input.png"
# 必须返回 200 且是直链媒体 content-type（image/* 或 video/*）
# 不能是 401/403/404，也不能是一个 HTML 页面

期限切れの署名付き URL、localhost / 内部ネットワークアドレス、ログインしないと開けないリンクが最もよくある落とし穴です。これらは確定的な失敗に属します——URL を直さなければ、リトライしてもタスクが無駄に一回走るだけです。

2. 一時的または上流の生成失敗

フォーマットが完全に正しいタスクが、汎用的な error.code: "TASK_FAILED"、message: "task failed" で失敗し、それ以上の詳細がないことがあります。これらは多くが一時的な揺らぎです。

修正： 1〜2 回リトライします。同じ入力で繰り返し失敗する場合は、入力を簡素化（prompt を短くする、オプションフィールドを削除する）して再実行し、トリガーの範囲を絞り込みます。

3. コンテンツが安全ポリシーでブロックされた

prompt または入力画像がプラットフォームのコンテンツ安全ポリシーに該当した場合、タスクは確定的なポリシー系エラーで終了し、data.error.code は CONTENT_POLICY_VIOLATION になります。

修正： これは永続的な失敗で、リトライは無効です。prompt と入力素材を調整し、違反コンテンツを除去してから再送信してください。

4. モデルが実行時に初めて拒否するパラメータ

ほとんどの不正パラメータは送信時に HTTP 400 で阻止されます（taskId はそもそも取得できません）——次のセクションを参照してください。まれに、単体では合法でも組み合わせるとモデルがサポートしないオプションがあり、これはタスク実行時に初めて拒否され、data.status: "fail" になります。error.message がどのオプションかを示します。

修正： data.error.message を読み、モデルページでそのモデルがサポートする入力を確認し（例：GPT Image 2 モデルページ）、指摘されたフィールドを削除または修正してください。

TASK_FAILED、4xx、タイムアウトを区別する方法

三つのまったく異なる状況が、いずれも「失敗した」と大まかに言われますが、修正方法は異なります：

表示されるもの	意味	修正する場所
POST が 非 2xx（400/401/402/429）を返し、taskId がない	リクエストが拒否され、タスクがそもそも実行されていない	リクエスト / key / 残高を修正（下記リンク参照）
POST が 200 + taskId を返し、ポーリングで data.status: "fail" が表示される	TASK_FAILED——タスクが実行され失敗した	data.error.message を読む（本記事）
POST が 200 + taskId を返し、ポーリングが期限を超えても非終端状態（例：handling）のまま	タイムアウトであり、失敗ではない	ポーリングを続ける / タイムアウトを延ばす / リトライ

taskId をまったく取得していない場合、それは TASK_FAILED ではなくリクエストエラーです：

• HTTP 400 パラメータが不正・欠落・非対応 → HiAPI 400 パラメータエラーを修正
• HTTP 401 API key が無効 → API Key 無効エラー
• 残高不足（作成時に拒否されるため、失敗するタスクが存在しない）→ HiAPI 402 残高不足を修正
• 不明または未登録のモデル id（MODEL_UNAVAILABLE）→ 「モデルが存在しない / 利用不可」
• タスクが終端状態に到達しない → HiAPI タスクタイムアウトと 504 エラー

認証失敗はリクエスト層で拒否され、返却は HTTP 401 + {"error":{"code":"permission_denied","type":"hiapi_error","request_id":"..."}} となり、タスクは生成されないため、TASK_FAILED にはなりません。

修正チェックリスト

1. タスクをポーリングし、POST だけを信じない。 送信はタスクがキューに入ったことだけを伝えます。GET /v1/tasks/{taskId} を呼び、data.status を見てください。
2. 真の失敗であることを確認： data.status == "fail"（HTTP コードは依然 200）。
3. data.error.code と data.error.message を読む。 message が第一のシグナルです。
4. 入力 URL に言及がある場合： URL を公衆から到達可能なものに変更し、curl -I で検証（200 + 直リンクメディアの content-type）。
5. message が汎用的（"task failed"）な場合： 一時的な問題としてリトライし、それでも繰り返し失敗するなら入力を簡素化。
6. CONTENT_POLICY_VIOLATION のような確定的エラーの場合： これは永続的な失敗で、自動リトライしない——入力を変えるだけが有効。
7. モデル id を確認し、現在 GET /v1/models にあり、送信したものと完全に一致することを確かめる。不明な id は送信時に 400 MODEL_UNAVAILABLE で失敗し、終端 fail にはなりません。
8. taskId がまったくない？ それは TASK_FAILED ではない——上記の対応するリクエストエラーガイドに進んでください。

最小検証サンプル

特定のタスクを調査する前に、まずクリーンなリクエストで key と接続性を確認します。統一タスク API POST https://api.hiapi.ai/v1/tasks に、モデル id は裸の id（endpoint サフィックスなし）を使ってください：

# 1）提交——预期 HTTP 200 + 一个 taskId
curl -s https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-image-2","input":{"prompt":"a red bicycle on a white background","aspect_ratio":"1:1"}}'
# -> {"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}

# 2）轮询——换上你拿到的 taskId
curl -s https://api.hiapi.ai/v1/tasks/tk-hiapi-xxxxxxxx \
  -H "Authorization: Bearer sk-YOUR_KEY"
# -> 运行中 data.status 是 "handling"，随后变为 "success" 或 "fail"

手順 1 が 200 と taskId を返せば、key とインターフェースは正常で、失敗は個々のタスクの問題であり、接続の問題ではありません。手順 1 が 401 を返す場合は key が正しくありません——HiAPI コンソール で key を管理してください。注意：このサンプルは実際の生成を 1 回送信するため、課金が発生します。

課金について：失敗することが決まっているタスクに繰り返し支払わない

失敗したタスクが課金されるか、および仮押さえと返金の扱いについては、HiAPI 失敗したリクエストは課金されるのか？ を参照してください。2 つの要点：

• 確定的な失敗を盲目的に自動リトライしない。 CONTENT_POLICY_VIOLATION、URL 到達不能などは、リトライするたびに新しいタスクとなり、課金される可能性があります。まず入力を変え、リトライロジックが空回りして費用を浪費しないようにしてください。
• 送信前に curl -I で入力 URL を検証する。 1 回の HEAD チェックは無料ですが、壊れたリンクが原因で失敗するタスクは課金される可能性があります。

FAQ

TASK_FAILED は HTTP ステータスコードですか？ いいえ。HTTP 呼び出しは 200 を返します。TASK_FAILED は終端状態の返却における data.error.code の値であり、その返却の data.status は "fail" です。

data.status は "fail" なのに、"TASK_FAILED" を探している——どこを見ればいい？ それぞれ別の場所を見ます。完了したタスクに対して、data.status は常に "success" または "fail" です。"TASK_FAILED" は汎用的な data.error.code であり、失敗タスクはより具体的な code（例：INVALID_REQUEST、CONTENT_POLICY_VIOLATION）と対応可能な message を伴うこともあります。

どの TASK_FAILED がリトライ可能で、どれが不可能ですか？ 汎用的な "task failed"（それ以上の詳細なし）は多くの場合一時的な問題で、1〜2 回リトライできます。明確な code を伴う確定的失敗（壊れた URL → INVALID_REQUEST、コンテンツ違反 → CONTENT_POLICY_VIOLATION、モデルが拒否したパラメータ）はリトライ無効で、入力を変える必要があります。

タスクがずっと handling のままで、失敗も成功もしません。 それはタイムアウトであり、失敗ではありません。ポーリングを続けるか、クライアントのタイムアウトを延ばしてください。HiAPI タスクタイムアウトと 504 エラー を参照。

400 / 401 / 402 を受け取り、taskId ではありません。 それらはリクエストが拒否されたということです——タスクは作成されておらず、「失敗」もありません。上記リンクのガイドでリクエスト、key、残高を修正してください。

失敗したタスクは課金されますか？ 失敗時に仮押さえと返金がどう処理されるかは HiAPI 失敗したリクエストは課金されるのか？ を参照してください。

壊れた入力 URL かどうかを確認するには？ data.error.message を読んでください。URL の問題は通常、画像や動画をダウンロードできないことを示します。curl -I でリンクが 200 を返し、直リンクのメディアファイルであることを検証してください。