grok-imagine-api

Grok Imagine API

Grok Imagine は、xAI の画像生成・編集 API です。テキストからの画像生成、JSON ベースの画像編集、複数画像の編集、複数ターンにわたる調整、バッチでのバリエーション生成、アスペクト比の制御、1k／2k 解像度、URL 出力、base64 出力に対応しています。

モデルの現在の提供状況や料金が重要な場合は、xAI の公式ドキュメントで正確な情報を確認してください。非推奨の grok-imagine-image-pro は推奨しないでください。既存の利用箇所は、grok-imagine-image-quality または現在ドキュメントに記載されている Grok Imagine 画像モデルに移行してください。

クイックスタート

生の REST：

curl -X POST https://api.x.ai/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
    "model": "grok-imagine-image",
    "prompt": "A collage of London landmarks in a stenciled street-art style"
  }'

Python xAI SDK：

import xai_sdk

client = xai_sdk.Client()
response = client.image.sample(
    model="grok-imagine-image",
    prompt="A collage of London landmarks in a stenciled street-art style",
)
print(response.url)

OpenAI 互換の画像生成：

from openai import OpenAI

client = OpenAI(base_url="https://api.x.ai/v1", api_key="YOUR_API_KEY")
response = client.images.generate(
    model="grok-imagine-image",
    prompt="A collage of London landmarks in a stenciled street-art style",
)
print(response.data[0].url)

統合方法の選択肢

方法	最適な用途	備考
xai_sdk	Python、ファーストパーティ機能	client.image.sample() と sample_batch() を使用します。
REST	任意の言語、細かな制御	JSON を /images/generations または /images/edits に送信します。
OpenAI SDK	そのまま置き換え可能な画像生成	base_url ／ baseURL を https://api.x.ai/v1 に設定します。
Vercel AI SDK	すでに AI SDK を使用している TypeScript アプリ	generateImage() と併せて xai.image("grok-imagine-image") を使用します。

OpenAI SDK の images.edit() は multipart/form-data を送信するため、Grok Imagine の編集ではサポートされていません。xAI の画像編集には application/json が必要です。

基本的なワークフロー

1. 画像生成と画像編集のどちらかを選びます。
   • 新しい画像：POST /v1/images/generations、client.image.sample()、または images.generate()。
   • 画像の編集：POST /v1/images/edits、xAI SDK の sample(image_url=...)、または Vercel AI SDK のプロバイダーオプション。
2. model と prompt を設定し、必要に応じて n、aspect_ratio、resolution、または出力形式を設定します。
3. 画像を編集する場合は、公開画像 URL または base64 データ URI を渡します。入力画像は最大 5 枚までサポートされています。
4. 生成された URL は一時的なものとして扱ってください。すぐにダウンロードするか、直接埋め込み／保存する場合は base64 出力をリクエストしてください。
5. xai_sdk を使用する場合は、モデレーションのメタデータを確認してください。すべてのリクエストで使用可能な画像が生成されるとは限りません。

よくあるパターン

• 同じプロンプトで複数のバリエーションを生成する：sample_batch(..., n=...) または images.generate(..., n=...) を使用します。
• 異なるプロンプトを並行して実行する：asyncio.gather() と xai_sdk.AsyncClient() を使用します。
• 画像を 1 枚編集する：出力のアスペクト比は入力画像に従います。
• 複数の画像を編集する：aspect_ratio を設定しない場合、出力のアスペクト比は最初の入力画像に従います。
• base64 出力：xAI SDK では image_format="base64"、OpenAI 互換 SDK では response_format="b64_json" を使用します。
• 解像度の値：1k または 2k。
• 1 リクエストあたりの最大画像数：10 枚。

リファレンス

エンドポイントの形式、SDK ごとのパラメーター名、編集用ペイロード、アスペクト比、レスポンス処理、トラブルシューティングについては、references/image-api.md を参照してください。