xAI Grok Imagine Image（標準グレード）による画像生成 API（非同期ジョブ）です。テキストからの生成は prompt だけで済み、編集は参照画像を image または images（URL、data:、base64）に入れるか /v1/images/edits を呼びます。送信するとすぐにジョブ id（HTTP 202）が返り、GET /v1/images/jobs/{id} をポーリングして画像を受け取ります。7 種類の比率と 1K / 2K の 2 段階に対応し（2K は resolution: "2K" か 2048 クラスのサイズを指定。4K は提供しておらず、指定すると送信時にエラーになります）、1K はふつう 5〜10 秒で出力します。標準グレードの編集は元画像の比率のまま出力し、別の比率を選ぶと中央で切り出します。1K と 2K は同じ料金で、失敗したリクエストは課金されません。
Playground で試す →認証
Authorization: Bearer YOUR_API_KEY Content-Type: application/json
コンソールで API Key を作成すると利用を開始できます。
リクエストボディ
| パラメータ | 種別 | 必須 | 説明 |
|---|---|---|---|
| model | string | はい | モデル ID。ここでは grok-imagine-image です。 |
| prompt | string | はい | 画像を説明するテキストプロンプト。 |
| size | string | いいえ | 出力の画面比率。1:1、3:4、2:3、9:16、4:3、3:2、16:9 のいずれかの比率を渡すのがおすすめで、モデルはその比率でネイティブに描画するため被写体が切れません。ピクセル指定（1024x1024、1024x1536、1536x1024 など）も受け付けます。既定は 1:1（正方形）です。 |
| n | integer | いいえ | 生成する画像の枚数。既定は 1 です。 |
| image | string | いいえ | 画像から画像：参照画像を公開 URL、data: URI、生の base64 のいずれかで渡します。指定すると、人物や被写体を保ったままの本物の画像から画像として、選んだサイズ・比率で生成します。/v1/images/edits の呼び出しと同等です。 |
| images | array | いいえ | 複数枚の参照画像（最大 8 枚。被写体の一貫性を保つには 4 枚以下を推奨）。文字列の配列か、[{"image_url": "..."}] というオブジェクトの配列で渡します。各要素は公開 URL、data: URI、base64 のいずれかです。複数参照の画像から画像として動作し、複数の参照の被写体とスタイルを融合します。/v1/images/edits の複数画像入力と同等です。1 枚だけなら上の image フィールドでも構いません。 |
| resolution | string | いいえ | 解像度：1K（既定）または 2K で、料金は同じです。size に 2048 クラスのピクセルサイズを指定しても 2K になります。4K は提供しておらず、指定すると拒否されます。 |
リクエスト例
# 1) submit -> 202 {"id":"img_...","status":"queued"}
curl https://nezhagate.com/v1/images/generations -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"model": "grok-imagine-image", "prompt": "a serene ink-wash poster, lots of negative space", "size": "1024x1536"}'
# 2) poll until status=succeeded
curl https://nezhagate.com/v1/images/jobs/img_3f9a...c2 -H 'Authorization: Bearer YOUR_API_KEY'レスポンス
{
"id": "img_3f9a...c2",
"object": "image.generation.job",
"status": "queued",
"model": "grok-imagine-image"
}画像から画像（Image-to-Image）
画像から画像：`image` に参照画像（公開 URL、data: URI、生の base64）を渡すと、人物や被写体を保ったままの本物の i2i として実行され、選んだサイズ・比率で描き直します。/v1/images/edits の呼び出しと同等です。
curl https://nezhagate.com/v1/images/generations -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d '{"model": "grok-imagine-image", "prompt": "背景を星空に差し替えてください", "image": "https://example.com/ref.png", "size": "3:4"}'画像ジョブ（送信 → 結果をポーリング）
画像の生成には通常 1〜3 分かかるため、画像エンドポイントはジョブ方式のみです。リクエストを送ると即座にジョブ ID が返り（HTTP 202）、その ID で結果をポーリングします。サーバーは再起動をまたいでも生成を続けるので、画像が失われることはありません。文字から画像でも画像から画像でも同じです。（従来の "async": true は不要になりました。受け付けますが無視されます。）
curl https://nezhagate.com/v1/images/generations -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"model": "grok-imagine-image", "prompt": "余白を大きくとった水墨画風のポスター", "size": "3:4"}'{ "id": "img_3f9a...c2", "object": "image.generation.job", "status": "queued", "model": "grok-imagine-image" }curl https://nezhagate.com/v1/images/jobs/img_3f9a...c2 -H 'Authorization: Bearer YOUR_API_KEY'
{
"id": "img_3f9a...c2",
"object": "image.generation.job",
"status": "succeeded",
"model": "grok-imagine-image",
"data": [{ "url": "https://img.nezhagate.com/i/9f86d081a8....png" }]
}🕑 data[0].url は当方の画像ホストのリンクで、60 日間保存された後に自動的に削除されます。継続して使う場合は、ダウンロードしてご自身のストレージや CDN に保存してください。
status は queued / processing / succeeded / failed のいずれかです。成功するとレスポンスに data[].url が入ります。ジョブをポーリングできるのは、それを作成したアカウントだけです。画像エンドポイントは常に非同期で、送信するとジョブ ID が返ります。"async": true は後方互換のためだけに受け付け、無視します。
エラーコード
エラー本文には常に error.message / error.type / error.code / error.param が含まれます。分岐は code で行ってください。一覧は接続ガイドにあります。
| HTTP | code | 説明 |
|---|---|---|
| 401 | invalid_api_key | API Key が欠落または無効 |
| 402 | insufficient_quota | 残高不足または Key が上限超過 |
| 400 | invalid_request | モデルまたはパラメータが非対応 |
| 429 | rate_limit_exceeded | 上流のレート制限 |
| 502 | upstream_error | すべての上流回線が失敗 |
