# Grok Imagine Image Quality — /images/generations

xAI Grok Imagine Image Quality（高品質グレード）による画像生成 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 と 2K は同じ料金で、失敗したリクエストは課金されません。

**エンドポイント:** `POST https://nezhagate.com/v1/images/generations`

## 認証
```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## リクエストボディ
| パラメータ | 種別 | 必須 | 説明 |
| --- | --- | --- | --- |
| `model` | string | はい | モデル ID。ここでは grok-imagine-image-quality です。 |
| `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 は提供しておらず、指定すると拒否されます。 |

## リクエスト例
```bash
# 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-quality", "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'
```

## レスポンス
```json
{
  "id": "img_3f9a...c2",
  "object": "image.generation.job",
  "status": "queued",
  "model": "grok-imagine-image-quality"
}
```

## 画像から画像（Image-to-Image）
画像から画像：`image` に参照画像（公開 URL、data: URI、生の base64）を渡すと、人物や被写体を保ったままの本物の i2i として実行され、選んだサイズ・比率で描き直します。/v1/images/edits の呼び出しと同等です。

```bash
curl https://nezhagate.com/v1/images/generations -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d '{"model": "grok-imagine-image-quality", "prompt": "change the background to a starry sky", "image": "https://example.com/ref.png", "size": "3:4"}'
```

## 画像ジョブ（送信 → 結果をポーリング）
画像の生成には通常 1〜3 分かかるため、画像エンドポイントはジョブ方式のみです。リクエストを送ると即座にジョブ ID が返り（HTTP 202）、その ID で結果をポーリングします。サーバーは再起動をまたいでも生成を続けるので、画像が失われることはありません。文字から画像でも画像から画像でも同じです。（従来の "async": true は不要になりました。受け付けますが無視されます。）

```bash
# ステップ 1 · ジョブを送信（すぐにジョブ ID が返ります、HTTP 202）
curl https://nezhagate.com/v1/images/generations -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"model": "grok-imagine-image-quality", "prompt": "an ink-wash poster", "size": "3:4"}'
# ステップ 2 · 結果をポーリング（status が succeeded になるまで 2〜3 秒ごと）
curl https://nezhagate.com/v1/images/jobs/img_3f9a...c2 -H 'Authorization: Bearer YOUR_API_KEY'
```

status は queued / processing / succeeded / failed のいずれかです。成功するとレスポンスに data[].url が入ります。ジョブをポーリングできるのは、それを作成したアカウントだけです。画像エンドポイントは常に非同期で、送信するとジョブ ID が返ります。"async": true は後方互換のためだけに受け付け、無視します。