メインコンテンツへスキップ
POST
Text-to-image: generate an image from a prompt (official channel)
🔒 申請制の GrokOfficial グループが必要です: Grok Imagine Official は Default グループには含まれていません。呼び出しを行う前(本ページのPlaygroundを含む)に利用申請が必要です。アクセス権限がない場合、またはリクエスト課金制の Token では、すべての呼び出しが 503 を返します。詳細はGrok Imagine Official 概要 - グループ設定をご覧ください。
右側のインタラクティブなPlaygroundで、エンドポイントを直接テストできます。Authorization に API Key を入力し(形式: Bearer sk-xxx)、prompt を入力してモデル、resolution、および aspect_ratio(2.0の場合はさらに quality)を選択し、送信します。
本ページを利用する場面: テキストからの画像生成、1回の呼び出しにつき1枚の画像。このチャネルは現時点では画像編集を提供していません。参照画像に基づく編集や1回の呼び出しで複数枚の画像を生成する場合は、Grok Imagine Reverseをご利用ください。
⚠️ よくある3つの落とし穴
  1. size ではなく resolution を使用する: size は解像度階層にマッピングされないため、画像はデフォルトの 1k で生成され、課金されます。
  2. 誤りがあるとエラーが返される: 範囲外の resolution / aspect_ratio は 422 を返し、quality: "high" は 400 を返します。これはリバースチャネルのサイレントフォールバックとは逆の動作です。
  3. 常に n = 1 を送信する: 複数枚の画像が必要な場合は、複数のリクエストを並行して送信してください。
すべての画像 API は同期型です。非同期タスク ID は存在しないため、クライアントが切断されると結果は失われますが、リクエストは課金されます。medium および 2K での grok-imagine-image-2.0 には約60〜80秒かかるため、クライアントのタイムアウトを360秒に設定してください。詳細は画像 API の注意事項とベストプラクティスをご覧ください。

コード例

Python (OpenAI SDK)

Python (requests)

cURL

Node.js (fetch)

パラメータクイックリファレンス

画像1枚あたりの価格(xAIと同じ):
モデルの価格設定は公式サイトに準拠しており、公式サイトの変更に伴って変動する場合があります。上記の表は参考情報であり、上部ナビゲーションのモデル価格タブが正式な情報となります:モデル価格。

レスポンス形式

  • data[] の各項目には、いずれかの url または b64_json が含まれ、どちらになるかは response_format によって異なります。
  • 返却された画像リンクはすぐにダウンロードしてください。そのまま参照し続けないでください。
  • usage はプレースホルダーであり(prompt_tokens は常に 1000 × image count です)、照合には使用できません — コンソールの課金記録が正式な情報となります。
  • created は常に 0 です。時間計測には使用しないでください。

関連ドキュメント

承認

Authorization
string
header
必須

API Key from the APIYI console (Token group must include GrokOfficial)

ボディ

application/json
model
enum<string>
デフォルト:grok-imagine-image
必須

Model ID:

  • grok-imagine-image — standard, $0.02 per image at every resolution
  • grok-imagine-image-quality — high quality, $0.05 / $0.06 / $0.07 at 1k / 1.5k / 2k
  • grok-imagine-image-2.0 — newer model, low $0.04 / $0.05 / $0.06, medium $0.06 / $0.07 / $0.08
利用可能なオプション:
grok-imagine-image,
grok-imagine-image-quality,
grok-imagine-image-2.0
prompt
string
必須

Prompt in any language. Describe the subject, scene, style, and lighting in detail

例:

"A photorealistic red wooden boat moored on a glassy alpine lake at dawn, mist over the water, snow-capped peaks behind, cinematic photography"

n
enum<integer>
デフォルト:1

Image count. Fixed at 1 on this channel; call concurrently for more images

利用可能なオプション:
1
resolution
enum<string>
デフォルト:1k

Resolution tier (lowercase), which also sets the price: 1k (default) / 1.5k / 2k.

Out-of-range values (such as 4k or 1K) return 422. Do not use size instead — it is not mapped to a resolution tier.

利用可能なオプション:
1k,
1.5k,
2k
aspect_ratio
enum<string>
デフォルト:1:1

Output aspect ratio, default 1:1. Measured examples: grok-imagine-image at 1k + 3:2 outputs 1248×832; -quality at 2k + 9:16 outputs 1584×2816.

Out-of-range values (such as 5:7) return 422.

利用可能なオプション:
1:1,
16:9,
9:16,
4:3,
3:4,
3:2,
2:3
quality
enum<string>

Quality tier, only for grok-imagine-image-2.0: low (default) or medium ($0.02 more per image, slower).

high returns 400. The other two models take no quality.

利用可能なオプション:
low,
medium
response_format
enum<string>
デフォルト:url

Response format: url (default; download and store the image right away) or b64_json (plain base64, no data: prefix)

利用可能なオプション:
url,
b64_json

レスポンス

Image generated successfully

created
integer

Always 0; do not use it for timing

例:

0

data
object[]

Image results (one item on this channel)

usage
object

Placeholder — do not reconcile with it. prompt_tokens is always 1000 × image count; the console billing records are authoritative