HiAPI 400 Bad Request：タスク API のパラメータエラーを修正する方法

統一非同期タスクインターフェースが 400 Bad Request を返す場合、リクエストは HiAPI に到達したものの、モデルが一切実行される前に拒否されたことを意味します。原因は JSON 自体、または input オブジェクトがそのモデルの schema に適合していないことです。レスポンスは次のようになります：

{
  "code": 400,
  "data": null,
  "error_code": "INVALID_REQUEST",
  "message": "invalid input: aspect_ratio: value must be one of '1:1', '4:3', '3:4', '16:9', '9:16'"
}

最も有用なフィールドは message です。具体的にどのパラメータが、どこで間違っているのかを示してくれます。400 はリクエスト自体の問題であり、認証や残高の問題ではありません。また、タスクがまったく作成されていないため、拒否された 400 には課金されません。

400 を引き起こすケース（発生確率の高い順）

以下はいずれも HTTP 400 を返します。schema の問題では error_code は INVALID_REQUEST、モデル id が存在しない場合は MODEL_UNAVAILABLE になります。以下はすべて HiAPI が実際に返すエラーメッセージです：

発生原因	実際に表示される message	error_code
列挙値が不正	invalid input: aspect_ratio: value must be one of '1:1', '4:3', '3:4', '16:9', '9:16'	INVALID_REQUEST
値の型が誤っている	invalid input: prompt: got number, want string	INVALID_REQUEST
必須フィールドの欠落 / フィールド名の誤り	invalid input: prompt: missing required field "prompt"; <root>: additional properties 'promptt' not allowed	INVALID_REQUEST
JSON 形式のエラー	invalid json body: unexpected end of JSON input	INVALID_REQUEST
モデル id が存在しない / 誤っている	model not available via /v1/tasks	MODEL_UNAVAILABLE

schema バリデータが実際に何を検出しているかに注目してください：列挙値（aspect_ratio、resolution などの値がそのモデルで許可された集合を外れている）、型（文字列を渡すべき場所に数値を渡した、または配列を渡すべき場所に裸の文字列を渡した）、フィールド名（promptt のようなスペルミス、または改名・削除されたフィールド——バリデータは「不足している必須フィールド」と「余分な未知のフィールド」を同時に報告します）、そしてモデル id 自体（値がタスクインターフェース上のオンラインモデルでない）です。

レスポンスボディから診断する方法

1. まず HTTP ステータスコードを確認します。 400 = リクエストに問題があります。401、402、403、429、504 の場合は別種の問題です——末尾の「関連記事」を参照してください。ステータスコードが実際には 401 なのに、400 としてパラメータを修正しないでください。
2. 次に error_code を確認します。 INVALID_REQUEST はリクエストボディ / input が schema 検証に失敗したことを意味し、MODEL_UNAVAILABLE は model の値が /v1/tasks 上で解決できないことを意味します。
3. message を一字一句読みます。 これはフィールド単位です：invalid input: <フィールド>: <原因>。invalid input: の後に続く語が修正すべきパラメータです。value must be one of ... と書かれていれば、許可された値がそこに示されています——そのまま1つコピーしてください。
4. additional properties '<x>' not allowed が出た場合、 そのモデルの schema で定義されていないフィールドを渡しています——通常はスペルミス、または別のモデルからコピーしたパラメータです。削除するか、正しいフィールド名に変更してください。

このフィールド単位のエラーメッセージには特筆すべき点があります。多くの画像・動画 API は、不正なリクエストに対して詳細を一切くれず、ただ 400 Bad Request とだけ返します。HiAPI はあなたの input を各モデル固有の schema と照合して検証し、どのフィールドが、何を期待しているのかを教えてくれます。そのため、当てずっぽうではなく、一度に1つのフィールドを正しく修正できます。

修正手順（チェックリスト）

1. まず JSON 形式を修正します。 message が invalid json body で始まる場合、payload 自体が有効な JSON ではありません——閉じていない波括弧・角括弧、余分なカンマ、エスケープされていない引用符がないか確認してください。送信前に jq や python -m json.tool で文字列を検証しましょう。
2. model が裸のオンライン id であることを確認します。 z-image、gpt-image-2 のような純粋な id を使用し、独自のルーティングサフィックスを考案しないでください。モデル一覧やモデルページと照合してください。存在しない id は MODEL_UNAVAILABLE を返します。
3. そのモデルの schema に合わせます。 各モデルはそれぞれ独自の input フィールドを宣言しています。生成パラメータはトップレベルではなく input の中に入れてください。schema に記載のないフィールドは削除します（それが additional properties ... not allowed の原因です）。
4. 列挙値はそのままコピーします。 message が value must be one of ... と表示した場合、そのうちの1つの値を一文字ずつコピーしてください（例："aspect_ratio": "1:1"）。
5. 正しい型を渡します。 prompt は文字列です。参照画像は配列フィールドに入れます（例：image_urls）。数値フィールドは数値でなければならず、引用符で囲んだ文字列にはできません。モデルによってフィールド名は異なる場合があります（参照画像は input_urls / image_urls / image_input、アスペクト比は aspect_ratio / ratio / size、duration は文字列の場合も整数の場合もあります）。必ずそのモデルの schema に従ってください。
6. 再送信して再度読みます。 それでも 400 の場合、message は今度は次のフィールドを指します。呼び出しが taskId を含む 200 を返すまで、1つずつ修正します。

最小限の動作するリクエスト

これは最小限の、正しい形式のテキストから画像への生成呼び出しです。これが data.taskId を含む 200 を返せば、キー、接続先アドレス、リクエスト構造に問題はありません——以前遭遇した 400 は接続問題ではなくパラメータの問題でした：

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "z-image",
    "input": {
      "prompt": "a red ceramic mug on a wooden table, soft daylight",
      "aspect_ratio": "1:1"
    }
  }'

送信に成功すると、data に taskId が含まれます。その後 GET https://api.hiapi.ai/v1/tasks/<taskId> をポーリングし、data.status が success（または fail）になるまで待ち、data.output から結果を読み取ります。デバッグ中はリクエストを最小限に保ってください。オプションフィールドを1つずつ戻していけば、新たに発生した 400 が、追加したばかりのフィールドを正確に指し示します。完全なフィールド一覧はモデルページ、タスクのライフサイクルは API ドキュメントを参照してください。

関連記事

• API Key 無効エラー：原因、修正、および連携チェックリスト —— ステータスコードが 400 ではなく 401 の場合に読む記事。
• HiAPI の「Model Not Found」を修正する —— MODEL_UNAVAILABLE とモデル id の問題に関する記事。
• HiAPI のレート制限（429）エラーを修正する方法 —— リクエスト検証ではなく、スロットリングに関する記事。
• HiAPI の失敗したリクエストは課金されますか？ —— 400 と「タスク実行後に失敗」の課金上の違い。
• 料金ページとダッシュボード：クレジットの確認、キーの取得。

FAQ

error_code: INVALID_REQUEST とはどういう意味ですか？ リクエストボディまたは input オブジェクトが schema 検証に失敗しました。message フィールドが、どのパラメータでエラーが起きたかを名指しします。認証の問題（それは 401）でも、残高の問題（それは 402）でもありません。

なぜ additional properties '<フィールド>' not allowed が発生するのですか？ そのモデルの schema で定義されていないフィールドを渡しています——通常はスペルミス（prompt を promptt と書いた）、別のモデルに属するフィールド、またはパラメータを input ではなくトップレベルに置いたことが原因です。削除するか、名前を変更してください。

400 Bad Request はクレジットを消費しますか？ いいえ。400 は検証段階で拒否され、タスクがまったく作成されていないため、課金されません。実際に受け付けられ、実行されたタスクのみが課金されます。

JSON に間違いがないことは確かなのに、まだ 400 になります。どうすればいいですか？ message を一字一句読んでください。フィールド単位で、正確なパラメータと期待される値または型を教えてくれます。value must be one of ... と書かれていれば、その値が許可された列挙値に含まれていないことを意味します——許可された値をそのまま1つコピーしてください。型を指摘されている場合（got number, want string）、型を正しく修正してください。

モデル id を間違えた場合も同じエラーですか？ やはり HTTP 400 ですが、error_code は MODEL_UNAVAILABLE で、メッセージは model not available via /v1/tasks です。裸の、現在オンラインのモデル id を使用し、独自のルーティングサフィックスを付けないでください。

あるモデルがどのフィールドを受け入れるかはどうやって調べますか？ 各モデルのページに、その input schema とサンプルリクエストが記載されています。上記の最小限の動作するリクエストから始めて、モデルページのドキュメントに従ってフィールドを1つずつ追加していってください。