> ## Documentation Index
> Fetch the complete documentation index at: https://docs.laozhang.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Grok Imagine APIの使い方：画像の生成と編集、1枚$0.055

> grok-imagine-image-2.0をxAIアカウントなしで呼び出せます。1Kまたは2Kの画像を1枚$0.055で生成し、最大3枚の参照画像で編集する手順を、コード付きで説明します。

Grok Imagine Image 2.0は、xAIの最新の画像モデルです。テキストからの生成も参照画像による編集も、OpenAI互換のImagesエンドポイントで行え、1回のリクエストで複数枚を返せます。

## grok-imagine-image-2.0の対応内容

| 項目 | 内容 |
| - | - |
| モデルID | `grok-imagine-image-2.0`（末尾の `.0` まで含む） |
| 料金 | `1k` または `2k`、`low` または `medium` のどれでも**1枚\$0.055**。生成も編集も同じで、正常に返された画像1枚ごとに課金 |
| アカウント | xAIアカウントは不要。LaoZhang APIのキーだけ |
| トークングループと課金方式 | `default`。従量優先（推奨）または回数課金 |
| エンドポイント | テキストからの生成：JSONの `POST /v1/images/generations`。参照画像による編集：multipartの `POST /v1/images/edits` |
| 同時実行とレート制限 | プラットフォーム側の同時実行数の上限や速度制限はありません。`429` は上流の処理能力に由来します。詳しくは[同時実行と429エラー](https://docs.laozhang.ai/ja/faq/api-concurrency.md) |
| 失敗したリクエスト | 画像がない200以外の応答は課金されません。タイムアウトしたあとは呼び出しログを確認してください。詳しくは[課金と失敗時の扱い](https://docs.laozhang.ai/ja/api-capabilities/image-billing-and-failures.md) |

公開価格は2026年9月24日時点のもので、2026年10月14日に確認しています。最新の価格は[モデルと料金](https://docs.laozhang.ai/ja/models.md)を参照してください。モデルはxAIが開発したもので、画像1枚ごとの固定料金で課金されます。

xAIは解像度と品質で価格を分けていて、1K mediumと2K lowが\$0.06、2K mediumが\$0.08です。編集では、入力画像1枚ごとに\$0.01が加わります（[xAIのモデルページ](https://docs.x.ai/docs/models/grok-imagine-image-2.0)、2026年10月13日に確認）。LaoZhang APIでは、これらがすべて\$0.055で、編集の入力料金もかかりません。

![日の出の海辺に立つ、映画のような灯台と海面の反射。Grok Imagine Image 2.0で生成](https://mintcdn.com/laozhangai-edd05f2c/YuJHjB7ivlJQODe0/images/samples/grok-generate.jpg?fit=max\&auto=format\&n=YuJHjB7ivlJQODe0\&q=85\&s=79f29d5f27a47afdbe81b006d15ddcf0)

下の生成例の出力：2K、16:9、medium。プロンプト：A cinematic lighthouse at sunrise, detailed ocean reflections, no text

### パラメーターと制限

| パラメーター | 値 |
| - | - |
| 編集1回あたりの参照画像 | 1〜3枚 |
| 解像度 | `1k` または `2k` |
| 品質 | `low` または `medium`。明示的に指定する |
| アスペクト比 | 固定の15種。省略するとモデルが選ぶ |
| 1回のリクエストの画像数 | `n` は1〜10。返された画像1枚ごとに課金 |
| レスポンス形式 | `url` または `b64_json` |

> [!WARNING]
>
> **編集で受け付けるのは、OpenAI互換のファイルアップロードです。参照画像が4枚以上のリクエストは失敗します。**
>
> * xAIのドキュメントにあるJSONの画像オブジェクトは使えません。
> * 3枚の上限はクライアントで必ず守り、上限を超えたリクエストは再試行しないでください。

## Grok Imagineのモデルを選ぶ

| モデルID | 対応範囲 | 向いている用途 |
| - | - | - |
| `grok-imagine-image-2.0` | 1K/2K、`low`/`medium`、固定15種の比率、1〜3枚の参照画像での編集 | 新規の連携、細部の描き込みが必要な画像、参照画像の合成 |
| `grok-imagine-image` | 2026年10月30日に提供終了 | 代わりに `grok-imagine-image-2.0` を使う |
| `grok-imagine-image-quality` | 以前の品質重視のモデルで、参照画像の上限が少ない | 既存の連携と、少量の最終素材の制作 |

以前の `grok-imagine-image-quality` は、1枚\$0.045です。2.0と同じく、正常に返された画像1枚ごとに課金されます。

* `grok-imagine-image`：2026年10月30日に提供を終了し、現在の呼び出しは503を返します。
  * `model` を `grok-imagine-image-2.0` に変えてください。
  * `aspect_ratio` と複数の参照画像による編集は、同じように動作します。
  * 詳しくは[提供終了のお知らせ](https://docs.laozhang.ai/en/announcements/grok-imagine-image-retired-2026-10.md)を参照してください。
* `grok-imagine-image-quality`：xAIは2026年11月2日からこのモデルを終了すると発表しています。
  * 終了後のリクエストは、`low` の品質で `grok-imagine-image-2.0` が処理します（[xAIの移行ガイド](https://docs.x.ai/developers/migration/imagine-image-quality-nov-2)）。
  * 2026年11月3日時点では、LaoZhang APIでまだ呼び出せます（1枚\$0.045）。新しく連携する場合は2.0を使い、`quality` を明示してください。

## APIを呼び出す前に

**1. APIキーを作成して保護する**

[トークン管理](https://api.laozhang.ai/token)で、`default` グループのキーを作成し、**課金方式**（计费模式）を**従量優先**（按量优先、推奨）または**回数課金**（按次计费）にします。従量優先のキーは、回数課金と従量課金の両方のモデルを呼び出せます。回数課金のキーが呼び出せるのは、回数課金のモデルだけです。

キーはサーバー側の環境変数に保存し、ブラウザ向けのコード、公開リポジトリ、ログには含めないでください。

**2. モデルへのアクセスと料金を確認する**

[モデルと料金](https://api.laozhang.ai/account/pricing)で、キーで `grok-imagine-image-2.0` が使えることと、現在の価格を確認します。

**3. 環境を整える**

キーをエクスポートし、Pythonの例で使うOpenAI Python SDKをインストールします。

```bash theme={null}
export LAOZHANG_API_KEY="YOUR_LAOZHANG_API_KEY"
python3 -m pip install openai
```

**4. まず1枚で試す**

最初は `n=1` で実行します。出力を保存して、内容と寸法を確認し、呼び出しの記録も見てから、解像度、出力枚数、同時実行数を増やしてください。

## 画像を生成する

このリクエストは、2K、16:9、`medium` 品質の画像を1枚生成し、レスポンスを `grok-generation.json` に書き出します。

```bash theme={null}
curl --fail-with-body "https://api.laozhang.ai/v1/images/generations" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-2.0",
    "prompt": "A cinematic lighthouse at sunrise, detailed ocean reflections, no text",
    "n": 1,
    "aspect_ratio": "16:9",
    "resolution": "2k",
    "quality": "medium",
    "response_format": "url"
  }' \
  -o grok-generation.json
```

成功すると、HTTP 200が返り、`data` に1件の項目が入ります。

```json theme={null}
{
  "data": [
    {
      "url": "https://..."
    }
  ]
}
```

### 結果を保存する

URLは一時的なものなので、すぐに画像をダウンロードしてください。次のスクリプトを `save_images.py` として保存します。レスポンスに含まれるすべての画像を、`url` でも `b64_json` でもディスクに保存し、拡張子は画像データから判定します。

```python save_images.py theme={null}
import base64
import json
import sys
import urllib.request
from pathlib import Path

response_file, stem = sys.argv[1], sys.argv[2]
response = json.loads(Path(response_file).read_text())
if not response.get("data"):
    sys.exit(f"{response_file} に画像が含まれていません: {response}")

for number, item in enumerate(response["data"], start=1):
    if item.get("b64_json"):
        # 先頭の data:image/...;base64, を取り除き、不足している = を補う
        value = item["b64_json"].split(",", 1)[-1]
        image = base64.b64decode(value + "=" * (-len(value) % 4))
    else:
        with urllib.request.urlopen(item["url"], timeout=120) as download:
            image = download.read()
    if image.startswith(b"\x89PNG"):
        extension = "png"
    elif image[:4] == b"RIFF" and image[8:12] == b"WEBP":
        extension = "webp"
    else:
        extension = "jpg"
    path = Path(f"{stem}-{number}.{extension}")
    path.write_bytes(image)
    print(f"保存しました: {path}")
```

```bash theme={null}
python3 save_images.py grok-generation.json grok-lighthouse
```

スクリプトは、`保存しました: grok-lighthouse-1.jpg` のような行を出力します。ファイルを開いて、被写体、文字、構図を確認してください。URLの代わりに画像のバイト列をレスポンスで受け取るには、`response_format` を `b64_json` にします。同じスクリプトで、どちらも処理できます。

### Python SDKで生成する

OpenAI Python SDKは、Grokの画像オプションのすべてを名前付きパラメーターとして用意しているわけではありません。`aspect_ratio`、`resolution`、`quality` は `extra_body` で渡します。この例はBase64で出力を受け取り、デコードした画像を保存します。

```python theme={null}
import base64
import os
from pathlib import Path

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["LAOZHANG_API_KEY"],
    base_url="https://api.laozhang.ai/v1",
    timeout=180,
)

response = client.images.generate(
    model="grok-imagine-image-2.0",
    prompt="ダークスレートの上に置かれた高級機械式腕時計、マクロの商品写真",
    n=1,
    response_format="b64_json",
    extra_body={
        "aspect_ratio": "1:1",
        "resolution": "2k",
        "quality": "medium",
    },
)

value = response.data[0].b64_json.split(",", 1)[-1]
image = base64.b64decode(value + "=" * (-len(value) % 4))
extension = "png" if image.startswith(b"\x89PNG") else "jpg"
output = Path(f"grok-watch.{extension}")
output.write_bytes(image)
print(f"保存しました: {output}")
```

## アスペクト比、解像度、品質

`grok-imagine-image-2.0` は、次の固定15種のアスペクト比を受け付けます。

| 向き | 値 |
| - | - |
| 正方形 | `1:1` |
| 横長 | `16:9`、`4:3`、`3:2`、`2:1`、`19.5:9`、`20:9`、`21:9`、`5:2` |
| 縦長 | `9:16`、`3:4`、`2:3`、`1:2`、`9:19.5`、`9:20` |

`aspect_ratio` を省略するとモデルが選びます。レイアウトを予測できるようにしたいときは、値を指定してください。

* `resolution="1k"`：高速で、下書き、サムネイル、バッチの候補に向いています。
* `resolution="2k"`：ファイルが大きく、待ち時間も長くなります。最終素材や、切り抜いて使う用途に向いています。
* `quality="low"`：速度を優先します。`quality="medium"` は細部を優先します。
* `quality="high"` と `resolution="4k"` は送らないでください。

レスポンスには、どの品質の段階が使われたかは含まれません。待ち時間と出力品質を予測できるよう、`auto` に任せず、`quality` は `low` か `medium` を明示してください。

## 参照画像1枚で編集する

編集にはファイルのアップロードが必要です。カレントディレクトリに `product-photo.png` を置いてから、次を実行します。

```bash theme={null}
curl --fail-with-body "https://api.laozhang.ai/v1/images/edits" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -F "model=grok-imagine-image-2.0" \
  -F "prompt=マグカップをマットブラックに変更してください。構図、照明、背景はそのままにしてください。" \
  -F "image=@product-photo.png" \
  -F "response_format=url" \
  -o grok-edit.json

python3 save_images.py grok-edit.json grok-edit
```

参照画像による編集はシーンを再生成する方式で、マスクを使ったピクセル単位のインペインティングではありません。保存した画像で、被写体、色、文字、構図を確認してください。

## 参照画像2〜3枚で編集する

参照画像ごとに、`image[]` フィールドを繰り返します。このリクエストは、被写体、シーン、スタイルを、3つの別々のファイルで渡します。

```bash theme={null}
curl --fail-with-body "https://api.laozhang.ai/v1/images/edits" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -F "model=grok-imagine-image-2.0" \
  -F "prompt=1枚目の画像の商品を2枚目の画像のシーンに置き、3枚目の画像のビジュアルスタイルを適用してください。商品の色は保ってください。" \
  -F "image[]=@product.png" \
  -F "image[]=@scene.jpg" \
  -F "image[]=@style.jpg" \
  -F "aspect_ratio=3:2" \
  -F "response_format=url" \
  -o grok-multi-edit.json

python3 save_images.py grok-multi-edit.json grok-multi-edit
```

アップロードした順番が、プロンプトの1枚目、2枚目、3枚目の画像に対応します。成功すると画像が1枚返り、`aspect_ratio=3:2` を指定すると、1248×832のような横長の結果になります。4枚目の参照画像を付けるとリクエスト全体が失敗するので、送る前にファイル数を数えてください。

### Python SDKで編集する

OpenAI SDKは、1枚の画像の編集に使えます。この例はURLを受け取り、すぐに画像をダウンロードします。

```python theme={null}
import os
import urllib.request
from pathlib import Path

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["LAOZHANG_API_KEY"],
    base_url="https://api.laozhang.ai/v1",
    timeout=180,
)

with open("product.png", "rb") as source:
    response = client.images.edit(
        model="grok-imagine-image-2.0",
        image=source,
        prompt="商品はそのままにして、背景を雨のネオン街に変えてください。",
        response_format="url",
    )

with urllib.request.urlopen(response.data[0].url, timeout=120) as download:
    image = download.read()
extension = "png" if image.startswith(b"\x89PNG") else "jpg"
output = Path(f"grok-sdk-edit.{extension}")
output.write_bytes(image)
print(f"保存しました: {output}")
```

複数の参照画像を使うときは、まず上のcURLの形式で試し、お使いのHTTPクライアントが、繰り返されるmultipartフィールドをどう送信するかを確認してください。

## パラメーター

| パラメーター | 型 | 必須 | 動作 |
| - | - | - | - |
| `model` | string | はい | `grok-imagine-image-2.0` |
| `prompt` | string | はい | 内容、構図、スタイル、そのまま保ちたい部分の詳細 |
| `n` | integer | いいえ | テキストからの生成で1〜10枚。返された画像1枚ごとに課金 |
| `aspect_ratio` | string | いいえ | 上の15種のどれか。省略するとモデルが選ぶ |
| `resolution` | string | いいえ | テキストからの生成では、小文字の `1k` または `2k` |
| `quality` | string | いいえ | `low` または `medium`。`high` は送らない |
| `response_format` | string | いいえ | `url` または `b64_json` |
| `image` | file | 1枚の編集では必須 | ローカルの画像1枚 |
| `image[]` | file | 複数枚の編集では必須 | フィールドを繰り返して、最大3つのファイルを渡す |

## 料金と課金

課金の対象は、リクエストで実際に返された画像の枚数です。

| リクエスト | 課金される枚数 |
| - | - |
| `n=1` で1枚返った | 1枚 |
| `n=4` で4枚返った | 4枚 |
| `n=10` で10枚返った | 10枚（現在の料金で\$0.55） |
| 参照画像3枚の編集で1枚返った | 1枚 |

LaoZhang APIでは、`1k` と `2k`、`low` と `medium` で料金は同じです。xAIは解像度と品質で価格を分けています。比較は、このページ冒頭の料金の説明にあります。

大量に実行する前に[コンソール](https://api.laozhang.ai/account/pricing)を確認し、最終的な課金の根拠は呼び出しの記録としてください。

## エラー処理

| 状況 | 想定される結果 | 対処 |
| - | - | - |
| 無効なAPIキー | 401 | キーを交換する。同じ認証情報で再試行しない |
| `prompt` がない | 400 | リクエストを修正する |
| `n` が10を超える | 429が返ることがある | `n` を1〜10の範囲でクライアント側で検証する |
| 未対応のアスペクト比 | 429が返ることがある | 上に挙げた値を使う |
| `resolution="4k"` | 503が返ることがある | `1k` または `2k` を使う。一時的な障害ではない |
| `quality="high"` | 画像が返ることがある | 気づかないうちに別の品質で処理され課金されるのを避けるため、クライアントで拒否する |
| 参照画像が4枚または5枚 | 500 | 3枚に減らす。同じリクエストを再試行しない |

有効なリクエストが429、ネットワークエラー、明らかに一時的な5xxエラーになった場合は、ジッター付きの指数バックオフで再試行します。クライアントがタイムアウトしたあとは、再送する前に呼び出しの記録を確認し、同じ画像を二重に生成して支払うことのないようにしてください。

## 本番環境に移行する前に

1. 本番用のキーで、`1k`、`low` の画像を1枚生成する。
2. 結果を保存し、実際の形式と寸法を確認する。
3. 使う予定の解像度、品質、アスペクト比、`n` の値を、そのまま試す。
4. 編集では、重複のない、機微でない参照画像を使い、どの画像も出力に影響していることを確認する。
5. 3枚の参照画像の上限を、クライアントで強制する。
6. タイムアウトは、`1k` の `low` で60秒以上、`medium` または `2k` で120〜180秒に設定する。
7. 同時実行数を増やす前に、成功率、待ち時間、出力枚数、呼び出しの記録を突き合わせる。

## よくある質問

### xAIアカウントなしで使えますか？

使えます。必要なのはLaoZhang APIのキーだけで、xAIアカウントは要りません。生成も編集も、OpenAI互換のImagesエンドポイントを使い、正常に返された画像1枚ごとに課金されます。

### 正確なモデルIDは？

末尾の `.0` を含めた `grok-imagine-image-2.0` を使ってください。以前の `grok-imagine-image` は2026年10月30日に提供を終了しました。`grok-imagine-image-quality` は別の以前のモデルで、xAIが11月2日からの終了を発表しているため、新しい連携には2.0を使ってください。

### 1枚ごとの課金ですか？解像度や品質で変わる？

正常に返された画像1枚ごとの課金です。`1k`、`2k`、`low`、`medium` は、現在すべて同じ1枚あたりの料金です。例は、前述の「料金と課金」を参照してください。

待ち時間は段階によって異なるため、タイムアウトはそれに合わせて決めてください。2026年10月14日にクイックスタートのプロンプトを実行したところ、1Kのlowは16秒、2Kのmediumは71秒かかり、どちらの呼び出しも\$0.055で記録されました。

![日の出の岩の多い海岸に立つ灯台と、海面に反射する日差し。Grok Imagine Image 2.0を1K lowで生成](https://mintcdn.com/laozhangai-edd05f2c/20UJZ-8MviaLAz5r/images/samples/grok-1k-low.jpg?fit=max\&auto=format\&n=20UJZ-8MviaLAz5r\&q=85\&s=f83ade14ebc124ee23ec1b56e1ab2ac3)

1K、low、16:9：16秒、\$0.055。プロンプト：A cinematic lighthouse at sunrise, detailed ocean reflections, no text

![日の出の岩の多い海岸に立つ灯台と、細かく描かれた雲と波。Grok Imagine Image 2.0を2K mediumで生成](https://mintcdn.com/laozhangai-edd05f2c/20UJZ-8MviaLAz5r/images/samples/grok-2k-medium.jpg?fit=max\&auto=format\&n=20UJZ-8MviaLAz5r\&q=85\&s=0911bebb8edf5ac6b2e8ac61deba42b3)

2K、medium、16:9：71秒、\$0.055。プロンプト：A cinematic lighthouse at sunrise, detailed ocean reflections, no text

200以外のエラーを返し、画像がないリクエストは、画像の課金対象になりません。ただし、クライアントのタイムアウトは失敗と同じではありません。サーバー側で画像が完成して課金されている場合があるため、再送する前に呼び出しの記録を確認してください。最終的な課金の根拠は呼び出しの記録です。

### JSON形式や4枚以上の参照画像は使えますか？

どちらも使えません。編集で受け付けるのは、multipartのファイルアップロードだけで、参照画像は最大3枚です。この点は、このページ冒頭の表のとおりです。xAIのJSONの画像オブジェクトは、HTTP 400を返します。

xAIのドキュメントには、OpenAI SDKの `images.edit()` はGrokの編集では動作しないと書かれています。これはxAI自身のJSON専用APIについての記述です。

LaoZhang APIでは、前述の「Python SDKで編集する」のとおり、1枚の画像の編集なら `images.edit()` が動作します。複数の参照画像を使うときは、まずcURLの `image[]` の形式で試してください。

### 編集結果のアスペクト比は？

xAIによると、`aspect_ratio` を指定しない編集は、1枚目の参照画像のアスペクト比に合わせます。フレームを固定したい場合は、編集リクエストに `aspect_ratio` を追加してください。3枚の参照画像を使う例では `aspect_ratio=3:2` を指定していて、1248×832の画像が返ります。

### 前の結果を続けて編集できますか？

できます。前の結果をダウンロードして `image` としてアップロードし、プロンプトには、今回の変更だけを書きます。たとえば、「ほかはそのままにして、金色の縁取りを加えてください」のように指示します。編集のたびに新しい編集リクエストとなり、返された画像の分が課金されます。

### 生成した画像はどう保存すべき？

URLの結果は、すぐに自分のストレージにダウンロードしてください。xAIも、返されるURLは一時的なものだと説明しています。画像をAPIのレスポンスの中で受け取りたいときは、`b64_json` を使います。

## 参考資料と関連ドキュメント

* [Grok Imagine Image 2.0の提供開始のお知らせ](https://docs.laozhang.ai/en/announcements/grok-imagine-image-2-0-2026-09.md)：提供状況と、3枚の参照画像までの編集の範囲
* [xAI Grok Imagine Image 2.0 model](https://docs.x.ai/developers/models/grok-imagine-image-2.0)：公式のモデルIDと、解像度・品質ごとの上流の価格
* [xAI image generation](https://docs.x.ai/developers/model-capabilities/images/generation)：公式のアスペクト比、解像度、品質、バッチ生成、レスポンス形式
* [xAI image editing](https://docs.x.ai/developers/model-capabilities/images/editing)：上流のJSON形式の編集。LaoZhang APIのmultipartインターフェースとは異なります
* [xAI multi-image editing](https://docs.x.ai/developers/model-capabilities/images/multi-image-editing)：複数画像の編集プロンプトの書き方。LaoZhang APIは、編集1回あたり最大3枚の参照画像を受け付けます
* [Images APIリファレンス](https://docs.laozhang.ai/ja/api-reference/images.md)：共通のリクエストとレスポンスの構造
* [画像APIの比較](https://docs.laozhang.ai/ja/api-capabilities/image-generation-guide.md)：Grok Imagineとほかの画像モデルの比較
* [コンソールのモデルと料金](https://api.laozhang.ai/account/pricing)：お使いのアカウントのモデル、グループ、価格、呼び出しの記録


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.