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

Imagen 4 Ultra は Google Imagen 4 シリーズの中で最も詳細度が高いバージョンです。hiapi 上では、他のすべての画像モデルと同様に、同一の統一非同期タスク API を通じてテキスト生成画像を実行します。本ガイドでは、実際に動作するリクエストを紹介します——本物の curl 呼び出し、Python ポーリングループ、サーバーが実際に受け付けるパラメータ、そして実際のリクエストで検証済みのエラー状況です。以下の内容はすべて公開前に本番エンドポイントで実行検証済みであり、例の taskId と出力 URL はその実行から取得したものです。

構築するもの

1 回の呼び出しでテキストプロンプトを完成画像に変換します：POST /v1/tasks にタスクを送信し、完了までポーリングし、output[0].url から画像 URL を読み取ります。hiapi API キーが必要です——ダッシュボードから取得してエクスポートしてください：

export HIAPI_API_KEY="your-hiapi-key"

最小限の動作例（curl）

このモデルは prompt と任意の aspect_ratio を受け付けます。タスクを作成します：

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "imagen-4.0-ultra",
    "input": {
      "prompt": "淡いオーク材のテーブルに置かれたマットなセラミック製コーヒーマグのマクロ商品写真、左側からの柔らかな窓の光、浅い被写界深度、手前に数粒のコーヒー豆、テキストなし、ロゴなし",
      "aspect_ratio": "4:3"
    }
  }'

作成呼び出しは即座にタスク ID を返します——生成はバックグラウンドで継続されます：

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

返された ID でタスクをポーリングします：

curl "https://api.hiapi.ai/v1/tasks/tk-hiapi-01M5CVC8R62M0Z7CCM8WB38B61" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

status が success のとき、画像は output[0].url にあります：

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M5CVC8R62M0Z7CCM8WB38B61",
    "model": "imagen-4.0-ultra",
    "status": "success",
    "storage": "temp",
    "created": 1792506471,
    "completed": 1792506479,
    "output": [
      {
        "artifactId": "279760",
        "type": "image",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M5CVC8R62M0Z7CCM8WB38B61-0.webp",
        "expireAt": 1793111279
      }
    ]
  },
  "message": "success"
}

その実行は約 8 秒で完了し、WebP（PNG/JPEG ではない）を返しました。URL は一時ストレージ上にあり（"storage": "temp"）、expireAt は 7 日後に設定されています——早めにダウンロードし、ホットリンクしないでください。

本番環境：ポーリングループ付き Python

作成レスポンスには画像は含まれません——taskId のみです。実際の統合では送信してからポーリングします（またはコールバックを使用します）。このスクリプトは完全な往復を実行し、URL が一時的なため結果を即座にダウンロードします：

import os, time, requests

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

def generate(prompt, aspect_ratio="1:1", negative_prompt=None, seed=None):
    body = {"model": "imagen-4.0-ultra", "input": {"prompt": prompt, "aspect_ratio": aspect_ratio}}
    if negative_prompt:
        body["input"]["negative_prompt"] = negative_prompt
    if seed is not None:
        body["input"]["seed"] = str(seed)  # seed is a STRING, not a number

    r = requests.post(API, headers=HEADERS, json=body, timeout=60)
    r.raise_for_status()
    created = r.json()
    if created.get("code") != 200:
        raise RuntimeError(f"create rejected: {created}")
    task_id = created["data"]["taskId"]

    # Poll. Statuses other than success/fail (e.g. queued, running, archiving) mean "keep waiting".
    for _ in range(60):
        time.sleep(3)
        try:
            d = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        except requests.RequestException:
            continue  # tolerate a transient read; re-poll the same id
        status = d.get("status")
        if status == "success":
            return d["output"][0]["url"]
        if status in ("fail", "failed", "error"):
            raise RuntimeError(f"task failed: {d}")
    raise TimeoutError(f"task {task_id} did not finish in time")

url = generate(
    "A high-detail aerial landscape of terraced rice fields at golden hour, long shadows",
    aspect_ratio="16:9",
)
img = requests.get(url, timeout=60).content
open("out.webp", "wb").write(img)
print(f"saved {len(img)} bytes from {url}")

本番環境で重要な注意事項：

• ポーリング vs コールバック。 上記はポーリングです。ポーリングを避けるには、トップレベルの callback オブジェクト（{"url": "...", "when": "final"}）を添付すると、タスクが終了状態に達したときに hiapi が POST リクエストを送信します。コールバック契約は統一非同期 API ドキュメントを参照してください。
• 保存した ID を再ポーリングし、再作成しない。 タスクの読み取りは冪等です。接続が切れた場合は GET /v1/tasks/<id> を再試行し、決して再度 POST しないでください（画像がもう 1 枚課金されます）。
• 成功したら即ダウンロード。 output[0].url は一時的です（今回の実行では TTL は 7 日）。バイトを取得して自分のストレージにプッシュしてください。

このモデルが実際に受け付けるパラメータ

imagen-4.0-ultra はテキスト生成画像のみをサポートします——参照画像はサポートしません（モデルページで確認済み；今回の実行ではテキスト生成画像のみをテスト）。入力 schema は閉じられており、未知のフィールドは拒否されるため、追加パラメータをこっそり渡すことはできません。

フィールド	型	必須	説明
prompt	string	はい	1〜5,000 文字。空文字列は失敗します（minLength: got 0, want 1）。
aspect_ratio	enum	いいえ	1:1、16:9、9:16、3:4、4:3、auto のいずれか。デフォルトは 1:1。
negative_prompt	string	いいえ	最大 5,000 文字。除外する内容を記述します。
seed	string	いいえ	最大 500 文字。文字列です——数値を渡すと拒否されます。

1 回のリクエストで生成される画像はちょうど 1 枚です。

検証済みのエラー状況

これらはすべて実際のエンドポイントで発生したものなので、エラーハンドリングの根拠にできます。拒否されたリクエストは HTTP 400 を返し、フラットなエンベロープを採用し、taskId は含まれません：

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

コード内で考慮すべきいくつかの挙動：

• バリデータはすべてのフィールドエラーを一度に報告し、; で連結します。seed に数値を渡し aspect_ratio が不正な場合、1 つのメッセージで両方が得られます：invalid input: seed: got number, want string; aspect_ratio: value must be one of ...。レスポンスごとにエラーは 1 つだけと仮定しないでください。
• 未知のフィールドはリクエスト全体を失敗させ、<root>: additional properties '<name>' not allowed というエラーになります。schema は閉じられています。
• 空のプロンプトは prompt: minLength: got 0, want 1 というエラーで失敗します。
• 成功した create は code: 200 で data.taskId を持ち、拒否された場合は data: null です。タスク ID を読み取る前にこれで分岐してください。

どの Imagen 4 ティアを呼び出すべきか？

imagen-4.0-ultra は 3 つのティアの中で最上位です。習慣ではなくタスクで選択してください（アスペクト比、ネガティブプロンプト、シードは支払う費用に影響しません——料金を参照）：

• Imagen 4 Fast —— 最も安価で、下書きのスキャンやバッチでの方向性探索に適しています。
• Imagen 4 —— 日常的な中間ティアで、商品、ライフスタイル、コンテンツ画像に適しています。
• Imagen 4 Ultra（本モデル）—— 3 つの中で最も高価で、完成品レベルのディテールに位置づけられます：マクロテクスチャ、マテリアルレンダリング、文字組みなど、最終画像が精査に耐える必要があるシーンに適用されます。出力をそのまま納品できる場合は Ultra を選び、反復時は Fast またはベーシックティアを使用してください。

関連リンク

• Imagen 4 Ultra モデルページ —— リアルタイム schema、例、料金。
• 統一非同期 API ドキュメント —— タスクの作成/一覧/取得およびコールバック契約。
• クイックスタート —— 数分で認証を完了し最初のタスクを実行。
• 料金 —— Imagen 4 各ティアの画像 1 枚あたりのコスト。

よくある質問

1 回のリクエストで何枚の画像が返りますか？ 1 枚です。検証済みの実行では、output 配列には 1 つのエントリのみが含まれていました。

出力形式は何ですか？ WebP です。返されるファイルは temp.hiapi.ai 上の .webp です。

出力 URL の有効期間はどのくらいですか？ 約 7 日間です——expireAt は完了から 7 日後に設定されます。一時リソースとして扱い、すぐにダウンロードしてください。

参照画像を送信できますか？ いいえ。imagen-4.0-ultra はテキスト生成画像のみをサポートし、モデルページでは参照画像は非サポートと記載されています。

なぜリクエストが "additional properties not allowed" でエラーになるのですか？ 入力 schema は閉じられています。prompt、aspect_ratio、negative_prompt、seed のみを送信してください。それ以外のキーはリクエスト全体を失敗させます。

ネガティブプロンプト、シード、アスペクト比は価格を変えますか？ いいえ。画像単位で課金され、これらのパラメータはコストに影響しません。