Grok Imagine画像API入門：curlとPythonで最初の1枚

Grok Imagine画像APIは、生成エンドポイントにpromptとモデルIDを送り、返された画像を保存して使います。 最初は出力1枚と明示的な設定で動作を確認し、その後にバッチ処理や編集を追加します。

対象はxAI直接接続のgrok-imagine-image-2.0です。2026年9月8日に公式生成ガイドで確認した仕様に基づく例で、有料生成を実行したという主張ではありません。対象サービスのキー、サーバー側の実行環境、素材の保存先が必要です。確認時点でOfoxはGrok Imagineを掲載しておらず、Ofoxのキーは直接接続に使えません。

curlで1枚生成する

通常のシークレット管理方法でXAI_API_KEYを設定し、端末またはバックエンドから実行します。実行するとAPI料金が発生します。公開するブラウザーコードにキーを含めないでください。

curl --fail-with-body --silent --show-error \
  --max-time 180 \
  https://api.x.ai/v1/images/generations \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-2.0",
    "prompt": "Studio photograph of a matte blue ceramic cup on a pale stone shelf, soft light from the left, no lettering",
    "n": 1,
    "aspect_ratio": "1:1",
    "resolution": "1k",
    "quality": "low",
    "response_format": "url"
  }' \
  -o grok-image-response.json

promptは作例であり、最も良い結果が出ると検証したものではありません。180秒のタイムアウトもアプリ側の設定で、生成時間の保証ではありません。終了ステータスと保存したJSONを確認してから成功と判断します。応答を残しておけば、URLがないエラー応答を誤ってダウンロード処理に渡さずに済みます。

Pythonで画像データを保存する

プロジェクト環境にrequestsをインストールしてから実行します。次の例はbase64形式を要求し、画像データの存在を確認してバイト列を保存します。

import base64
import os
from pathlib import Path

import requests

payload = {
    "model": "grok-imagine-image-2.0",
    "prompt": (
        "Studio photograph of a matte blue ceramic cup on a pale "
        "stone shelf, soft light from the left, no lettering"
    ),
    "n": 1,
    "aspect_ratio": "1:1",
    "resolution": "1k",
    "quality": "low",
    "response_format": "b64_json",
}
response = requests.post(
    "https://api.x.ai/v1/images/generations",
    headers={"Authorization": f"Bearer {os.environ['XAI_API_KEY']}"},
    json=payload,
    timeout=(10, 180),
)
response.raise_for_status()
body = response.json()
images = body.get("data", [])
if not images or not images[0].get("b64_json"):
    raise RuntimeError("No base64 image returned; inspect response metadata")
image_bytes = base64.b64decode(images[0]["b64_json"], validate=True)
# Keep raw bytes until your image decoder identifies the returned format.
output = Path("grok-image-output.bin")
output.write_bytes(image_bytes)
print(f"Saved {len(image_bytes)} bytes to {output}")

.binは、未確認の形式をPNGやJPEGと決めつけないための拡張子です。アプリでは画像デコーダーで形式と寸法を確認し、適切な拡張子とメディアタイプで保存してください。

URL形式も利用できますが、返される画像URLは一時的です。継続して使う素材は早めに自分のストレージへ保存します。応答形式の説明を確認してください。

バッチ化する前に仕様を記録する

必要な縦横比、予算上の画質、出力枚数を決めます。各生成について、業務のジョブID、モデルと提供元、要求設定、promptまたはテンプレートの版、保存先、採用結果を記録すると追跡できます。

生成と編集は別の処理として設計します。編集には入力画像と専用のスキーマ、予算が必要です。生成リクエストに任意のimageフィールドを足すだけで通るとは限りません。編集ドキュメントを確認します。

再試行の前に確認すること

接続失敗、HTTPエラー、成功応答の内容不備を分けて調べます。認証エラーなら宛先ホストとキーの発行元、検証エラーなら最小限のリクエストと拒否されたパラメーターを確認してください。

送信後のタイムアウトでは、サーバー側で生成が完了したかクライアントには分からない場合があります。確認せず有料処理を自動で繰り返さず、ジョブに応答メタデータを残します。Authorizationヘッダーはログに保存しません。審査に関わる応答はサービスのルールと照合し、未対応の要求をループで解決しようとしないことが大切です。

一般的な問題は画像生成の失敗対策も参考になります。パラメーター名は実際の提供元の仕様を使ってください。

既存アプリへの組み込み

提供元固有のフィールドは小さなアダプターにまとめ、業務側ではprompt、参照素材、出力形状を扱います。同じ制作要件を保ったまま接続先を比較しやすくなります。FLUX接続ガイドも設計の参考にできます。

量を増やす前にImage 2.0の料金を計算し、旧別名を使っている場合はqualityモデル移行を確認しましょう。