imagen-4.0-fast API：実際に動作するテキストから画像生成のリクエスト

Imagen 4 Fast は Google Imagen 4 シリーズの高速版であり、hiapi では他のすべての画像モデルと同じ統一非同期タスク API を通じてテキストから画像を生成します。本ガイドでは、実際に動作するリクエストを提供します——実際の curl 呼び出し、Python のポーリングループ、正確なクローズド形式の入力 schema、そして本番環境で検証済みのエラーケースです。以下の内容はすべて公開前に本番エンドポイントに対して実行されており、例に登場する taskId と出力 URL はその実行から得られたものです。

実現できること

1回の呼び出しでテキストプロンプトを完成した画像に変換します：POST /v1/tasks にタスクを送信し、完了するまでポーリングしてから画像 URL を読み取ります。hiapi API キーが必要です（コンソールで作成し、アカウントに従量課金のクレジットをいくらか保持しておいてください——料金を参照）。SDK は不要で、ここでのすべての例は純粋な HTTP です。

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

タスクを作成します。モデル id は imagen-4.0-fast で、このティアでは aspect_ratio が必須です（後述の詳細を参照）：

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "imagen-4.0-fast",
    "input": {
      "prompt": "Colorful isometric city block with tiny cars and trees; playful 3D illustration",
      "aspect_ratio": "16:9"
    }
  }'

作成呼び出しはタスクハンドルだけを返します——画像ではありません：

{ "code": 200, "data": { "taskId": "tk-hiapi-01M5D4ZD2X353AHHW3SW8X8N0A" }, "message": "success" }

結果のポーリング（Python）

taskId を取得したら、ステータスが終了状態になるまで GET /v1/tasks/<id> をポーリングします。以下は実際に実行したループです：

import os, time, requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

# 1. create the task
created = requests.post(API, headers=HEADERS, json={
    "model": "imagen-4.0-fast",
    "input": {
        "prompt": "Colorful isometric city block with tiny cars and trees; playful 3D illustration",
        "aspect_ratio": "16:9",
    },
}).json()
task_id = created["data"]["taskId"]

# 2. poll until the task reaches a terminal state
while True:
    data = requests.get(f"{API}/{task_id}", headers=HEADERS).json()["data"]
    status = data["status"]
    if status == "success":
        print(data["output"][0]["url"])   # the finished image
        break
    if status == "fail":
        raise RuntimeError(data)
    time.sleep(3)

私の実行では、ステータスは約12秒で handling → archiving → success と遷移し、終了状態のレスポンスは次のとおりでした：

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M5D4ZD2X353AHHW3SW8X8N0A",
    "model": "imagen-4.0-fast",
    "status": "success",
    "storage": "temp",
    "output": [
      {
        "type": "image",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M5D4ZD2X353AHHW3SW8X8N0A-0.webp",
        "expireAt": 1793121346
      }
    ]
  },
  "message": "success"
}

1つのタスクは1枚の WebP 画像を返します。archiving ステータスは正常です——短時間留まった後、success に切り替わります。

入力 schema（サーバーが実際に受け付ける内容）

input オブジェクトはクローズド形式の schema です。以下のフィールドのみを受け付けます：

フィールド	型	必須	説明
prompt	string	はい	空でないこと。空文字列は minLength: got 0, want 1 を返します。
aspect_ratio	enum	はい	1:1、16:9、9:16、3:4、4:3、auto のいずれか。デフォルト値はありません。
seed	integer	いいえ	再現可能な実行に使用します。JSON の数値である必要があり、文字列は不可です。
negative_prompt	string	いいえ	画像に含めたくない内容を記述します。

このモデルには resolution や size フィールドはありません——出力サイズは aspect_ratio に従います。この表以外のフィールドは拒否されます。

検証済みのエラーケース（落とし穴）

これらは推測ではありません——すべて本番エンドポイントに対して取得した実際の 400 レスポンスです。

1. aspect_ratio の欠落。 ベースの Imagen 4 や Ultra ティアからコードスニペットをコピーすると発生する最大の落とし穴です。なぜなら、そちらでは aspect_ratio のデフォルトが 1:1 だからです。Fast にはデフォルトがありません：

{ "code": 400, "error_code": "INVALID_REQUEST",
  "message": "invalid input: aspect_ratio: missing required field \"aspect_ratio\"; prompt: minLength: got 0, want 1" }

2. seed を文字列として送信。 数値として渡してください：

{ "code": 400, "error_code": "INVALID_REQUEST",
  "message": "invalid input: seed: got string, want integer" }

3. 不明なフィールド（ここでは resolution）——クローズド形式の schema は余分な内容をすべて拒否します：

{ "code": 400, "error_code": "INVALID_REQUEST",
  "message": "invalid input: <root>: additional properties 'resolution' not allowed" }

その形に注意してください：検証失敗は HTTP 400 であり、error_code: "INVALID_REQUEST" を伴い、taskId はなく、message は各フィールドのエラーを ; 区切りの1つの文字列に集約します——したがって最初の文だけでなく全体を読む必要があります。

Fast と Imagen 4 シリーズの他のティアとの比較

hiapi はまったく同じタスク API 上で3つの Imagen 4 ティアをホストしており、異なるのは model id だけなので、上記のリクエストボディはすべてのティアで共通です：

• imagen-4.0-fast——高速ティア（モデルページ）であり、このシリーズで最も低コストな選択肢です。プロンプトの反復、概念探索、大量の候補を生成して少数を残すバッチ方向探索に適しています。
• imagen-4.0——標準の Imagen 4 ティア。
• imagen-4.0-ultra——最高ディテールティアで、納品品質の最終出力に使用します。

実用的なワークフロー：Fast でプロトタイプを作成し、その後 model 文字列を imagen-4.0-ultra に置き換えて最終レンダリングを行います。他のコードを一切変更する必要はありません。現在の1枚あたりの価格は料金ページで比較してください。

本番環境での注意事項

• ポーリング vs. webhook。 上記のループはポーリングです。本番環境では、hiapi のタスク API は webhook もサポートしています：トップレベルの callback オブジェクト（model/input と同じ階層）に url と when: "final" を含めると、hiapi はタスクが終了状態に達したときにタスク詳細を POST します。依存する前に、非同期 API ドキュメントで配信とリトライの規約を確認してください。
• ネットワークが不安定なときに再送信しないでください。 タスク作成のたびに新しい taskId が返されます——プロンプトの重複排除はありません。ポーリングリクエストが一時的に失敗した場合は、既に保存している taskId で再度ポーリングしてください。taskId を一度も受け取っていない場合にのみ、POST をやり直す必要があります。
• 出力 URL は期限切れになります。 output[].url は temp.hiapi.ai 上にあり、その expireAt は約7日後です（上記の例は 2026-10-28 に期限切れ）。バイトデータを直ちに自身のストレージにダウンロードしてください。ホットリンクはしないでください。

関連コンテンツ

• Imagen 4 Fast モデルページ
• Imagen 4 Ultra——最高ディテールティア、リクエスト構造は同一
• Imagen 4（ベース版）
• 統一非同期タスク API ドキュメント
• 料金

よくある質問

Imagen 4 Fast には異なるエンドポイントや SDK が必要ですか？ いいえ。POST /v1/tasks に "model": "imagen-4.0-fast" を付けるだけです——hiapi のすべての画像・動画モデルが使用するのと同じエンドポイントです。モデル id を変更することでティアを切り替えます。

なぜ私のリクエストは「missing required field aspect_ratio」という 400 を返すのですか？ Fast にはデフォルトのアスペクト比がありません（ベース版や Ultra ティアとは異なります）。列挙 1:1 | 16:9 | 9:16 | 3:4 | 4:3 | auto から常に aspect_ratio を送信してください。

解像度や画像サイズを設定できますか？ いいえ——このモデルには resolution や size フィールドはありません。出力サイズは aspect_ratio に従います。resolution を送信すると additional properties 'resolution' not allowed が返されます。

seed は文字列ですか、数値ですか？ 数値です。"seed": 7 は使用可能で、"seed": "7" は seed: got string, want integer を返します。

出力 URL の有効期間はどのくらいですか？ 約7日間です（expireAt）。直ちにダウンロードして保存してください。