Imagen 4 API の使い方？5分で最初の1枚を生成

TL;DR

• Imagen 4（imagen-4.0）はテキストから画像を生成するモデルで、1枚 $0.06：プロンプトを1文書いて画角を選べば画像が出ます。ポートレート写真、自然のクローズアップ、商品の静物に適しています。モデルページを開くとオンラインで試せて、新規ユーザー登録で200クレジットが付与されます。
• 同じシリーズにはもう2グレードあります：imagen-4.0-fast は1枚 $0.03 で大量の試し描きに、imagen-4.0-ultra は1枚 $0.09 で完成品のディテールに使います。
• 呼び出しは HiAPI の /v1/tasks エンドポイント経由：タスクを送信して taskId を取得し、結果を照会して、成功後に output[0].url から画像をダウンロードします。

できること

• テキストから直接画像生成：参照画像は受け取らず、画面はすべてプロンプトで記述します。aspect_ratio は必須（1:1、16:9、9:16、3:4、4:3、auto の6種類）。
• 3つの位置づけを1シリーズで：Fast は試し描き、標準グレードは日常の制作、Ultra はディテール向上に使い、3つのモデル ID を同じプロジェクトで段階的に使い分けます。
• 毎回1枚固定：枚数、ピクセルサイズ、出力形式のパラメータはなく、再実行すれば seed が変わります。

以下は標準グレードの実際の成果物です：

Sunlit Scandinavian living room with linen sofa; oak shelves and a monstera plant; editorial interior photography

（日本語の意味：日当たりの良い北欧風リビング、リネンのソファ、オーク材の棚とモンステラ；雑誌風のインテリア写真。画角は16:9を選択。）

imagen-4.0、16:9、1280×720、$0.06。

このプロンプトで生成 →

3つのモデルの選び方

	imagen-4.0-fast	imagen-4.0（標準）	imagen-4.0-ultra
1枚あたり	$0.03	$0.06	$0.09
位置づけ	大量の試し描き、方向性の絞り込み	日常の制作	完成品のディテール、質感と文字組み
$10 で約	333 枚	166 枚	111 枚
適する用途	企画会議、ラフ案のラウンド	通常の画像納品	最終稿、ディテールに敏感な画面

予算の目安：すべて標準グレードで月1,000枚なら約 $60.00；試し描きを Fast に回すほど請求は抑えられ、最終稿の分を Ultra に残します。

3つのモデルは呼び出し方が同じで、model フィールドを変えるだけです；パラメータ構造も同一で、seed の型だけが異なります（パラメータ表参照）。Fast と Ultra にはそれぞれ英語版の導入チュートリアルがあります：Imagen 4 Fast API guide、Imagen 4 Ultra API guide。シーン別のプロンプト選びはプロンプト大全を、3グレードの完全な料金表と月予算は料金ページを、Nano Banana 2.1 との同一プロンプト2組の比較は比較ページをご覧ください。

2つの導入ルート

ブラウザで3ステップ：モデルページを開く → プロンプトを貼り付けて画角を選ぶ → 生成をクリック、標準グレードで1枚 $0.06。最初はブラウザで1枚生成して画面のスタイルが期待通りか確認してから、コードを書き始めるのがおすすめです。

API で3ステップ：POST /v1/tasks で送信 → taskId を取得 → GET /v1/tasks/<taskId> で success を確認してダウンロード。

curl：最初の1枚

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: your-unique-key-001" \
  -d '{
  "model": "imagen-4.0",
  "input": {
    "prompt": "Sunlit Scandinavian living room with linen sofa; oak shelves and a monstera plant; editorial interior photography",
    "aspect_ratio": "16:9"
  }
}'

グレードを変えるには model だけ変更：imagen-4.0-fast または imagen-4.0-ultra。返却値の taskId が照会のキーです。

Python：送信、ポーリング、ダウンロード

import time, uuid, requests

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}

payload = {
    "model": "imagen-4.0",
    "input": {
        "prompt": "Sunlit Scandinavian living room with linen sofa; oak shelves and a monstera plant; editorial interior photography",
        "aspect_ratio": "16:9",
    },
}

# 送信：Idempotency-Key を付けると、ネットワークリトライでもタスクが重複作成されない
resp = requests.post(
    BASE,
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
    json=payload,
    timeout=30,
)
resp.raise_for_status()
task_id = resp.json()["taskId"]

# ポーリング：queued -> handling -> archiving -> success / fail
while True:
    task = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()
    print(task["status"])
    if task["status"] in ("success", "fail"):
        break
    time.sleep(3)

if task["status"] == "success":
    image_url = task["output"][0]["url"]   # 一時URL、できるだけ早くダウンロードして保存
    img = requests.get(image_url, timeout=60)
    with open("output_image", "wb") as f:  # 拡張子は実際に返された形式に合わせて命名
        f.write(img.content)
    print("saved")

パラメータ表

フィールド	必須	値	説明
prompt	はい	1–5000 文字	画面内容の記述
aspect_ratio	はい	1:1 / 16:9 / 9:16 / 3:4 / 4:3 / auto	出力画角、必須
negative_prompt	いいえ	≤5000 文字	出現させたくない内容
seed	いいえ	標準グレードと Ultra：文字列（≤500 文字）；Fast：整数	同じパラメータと同じ seed で画面を再現

3つのモデルは同じパラメータ表を共有します。リクエストボディに表外のフィールドが含まれると直接 400 になります。

遭遇するエラー

ステータスコード	意味	対処方法
400 INVALID_REQUEST	リクエストボディが不正（prompt または aspect_ratio の欠落、列挙値の誤り、表外フィールドの送信）	パラメータ表に照らしてリクエストボディを修正
402 INSUFFICIENT_QUOTA	残高不足（課金なし）	チャージ後に再試行
429 RATE_LIMITED	レート制限に抵触	送信頻度を下げる
409 / 422 IDEMPOTENCY_KEY_*	同じ冪等キーで重複送信（処理中 / パラメータ不一致）	新しい Idempotency-Key に変更
415 UNSUPPORTED_MEDIA_TYPE	リクエスト形式が不正	Content-Type: application/json を確認

タスクが終端状態で失敗した場合、エラーコードには他に CONTENT_POLICY_VIOLATION、TASK_FAILED、TASK_TIMEOUT などがあります；失敗時は課金されず、事前に確保したクレジットは全額返還されます。

公開前の注意点

• コールバック：リクエストボディのトップレベルに "callback": {"url": "https://..."} を渡すと、タスクが終端状態になった際にサービスへ通知され、ポーリングを省けます。
• 速やかに転送保存：output[0].url は一時URLなので、取得したらすぐにダウンロードして自分のストレージに保存します。
• 画角を明示的に指定：aspect_ratio は必須項目なので、デフォルト値に頼らないこと；縦型のソーシャルメディア向けコンテンツには 9:16 を選びます。
• seed の型はモデル別：Fast は整数、標準グレードと Ultra は文字列を渡します。

よくある質問

3つのモデルの呼び出し方は同じですか？

同じです。model フィールドを変えるだけで、他のコードは変更不要です。

ピクセルサイズや出力形式を指定できますか？

できません。ピクセルサイズと形式のパラメータはなく、出力画角は aspect_ratio で決まり、毎回1枚です。

失敗すると課金されますか？

されません。事前に確保したクレジットは失敗の終端状態後に全額返還されます。

画面内の文字は信頼できますか？

拡大して確認が必要です。ポスター系の生成画像はときどき文字が1つ多かったり画が1本足りなかったりするので、公開前に文字部分を拡大して一通り確認してください。

3グレードの画像を1つのプロジェクトに混在できますか？

できます。プロンプトと画角のロジックは共通です。

次のステップ：上のリビングのプロンプトをコピーしてモデルページで1枚試し、その後、シーン別にプロンプト大全のテンプレートでバッチ生成しましょう。