> ## 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.

# Images APIの使い方：画像の生成と編集

> LaoZhang APIで、テキストから画像を生成し、既存の画像をアップロードして編集します。ファイルのアップロードと結果の保存まで、cURLとPythonの完全な例で説明します。

生成と編集の2つのエンドポイントは、どちらもOpenAIのImages APIと同じ形式でレスポンスを返します。

| 項目 | 内容 |
| - | - |
| 生成 | `POST /v1/images/generations` |
| 編集 | `POST /v1/images/edits` |
| 結果 | `data[]` の各画像。`b64_json` か `url` のどちらかで返る |
| 例で使うモデル | 生成は `gpt-image-2.5-flare-vip`、編集は `gpt-image-2.5-sunburst-vip` |

Nano BananaのモデルでGeminiネイティブの画像生成と編集を行う場合は、[Nano Bananaの概要](https://docs.laozhang.ai/ja/api-capabilities/nano-banana-image.md)を参照してください。画像モデルとエンドポイントの比較は、[画像APIの比較](https://docs.laozhang.ai/ja/api-capabilities/image-generation-guide.md)にあります。

## 認証情報を設定する

[トークン管理](https://api.laozhang.ai/token)でモデル用のAPIキーを作成し、環境変数 `LAOZHANG_API_KEY` に設定します。キーのグループでGPT Image 2.5のVIPモデルを使えることを、コンソールの[モデルと料金](https://api.laozhang.ai/account/pricing)で確認してください。

ターミナルで、プレースホルダーを置き換えてキーを設定します。

```bash theme={null}
export LAOZHANG_API_KEY="YOUR_LAOZHANG_API_KEY"
```

以下の例では、次の値を使います。

* **APIホスト：** `https://api.laozhang.ai`
* **OpenAI SDKのベースURL：** `https://api.laozhang.ai/v1`
* **認証：** `Authorization: Bearer $LAOZHANG_API_KEY`
* **モデル：** `gpt-image-2.5-flare-vip`（生成）と `gpt-image-2.5-sunburst-vip`（編集）

APIの呼び出しと画像の保存に使うPythonパッケージをインストールします。cURLの例でも、レスポンスのデコードと正しい拡張子の判定にPythonを使います。

```bash theme={null}
python -m pip install openai pillow httpx
```

### レスポンスから画像を保存する

次のヘルパーを、例を実行するディレクトリに `save_images.py` として保存します。`data[]` の各エントリーが `b64_json` と `url` のどちらでも、すべての画像をファイルに書き出します。

```python theme={null}
"""OpenAI Images APIのレスポンスに含まれるすべての画像を保存する。"""
import base64
import io
import json
import sys
from pathlib import Path

import httpx
from PIL import Image

EXTENSIONS = {"PNG": "png", "JPEG": "jpg", "WEBP": "webp"}


def image_bytes(item):
    """data[] の1エントリーから画像のバイト列を返す。"""
    encoded = item.get("b64_json")
    if encoded:
        encoded = "".join(encoded.split())
        if encoded.startswith("data:"):
            encoded = encoded.split(",", 1)[1]  # data:image/...;base64, の接頭辞を取り除く
        encoded += "=" * (-len(encoded) % 4)  # 欠けたパディングを補う
        return base64.b64decode(encoded)
    if item.get("url"):
        # LaoZhang APIのキーは送らずに結果をダウンロードする
        download = httpx.get(item["url"], timeout=120, follow_redirects=True)
        download.raise_for_status()
        return download.content
    raise ValueError("data[] のエントリーに b64_json も url もありません")


def save_images(response, stem):
    """各画像を <stem>.<拡張子>、<stem>-2.<拡張子> … の順に保存する。"""
    entries = response.get("data") or []
    if not entries:
        raise RuntimeError(f"レスポンスに画像がありません: {json.dumps(response)[:500]}")
    for number, item in enumerate(entries, start=1):
        raw = image_bytes(item)
        with Image.open(io.BytesIO(raw)) as image:
            image.load()
            extension = EXTENSIONS.get(image.format, (image.format or "bin").lower())
            size = f"{image.width} × {image.height}"
        suffix = "" if number == 1 else f"-{number}"
        output = Path(f"{stem}{suffix}.{extension}")
        output.write_bytes(raw)
        print(f"保存しました: {output}（{size}）")


if __name__ == "__main__":
    save_images(json.loads(Path(sys.argv[1]).read_text(encoding="utf-8")), sys.argv[2])
```

cURLのリクエストのあとに `python save_images.py <response.json> <名前>` として実行するか、Pythonで `save_images` をインポートして使います。

## 画像を生成する

`model` と `prompt` を含むJSONの本文を、次のエンドポイントに送ります。

```text theme={null}
POST https://api.laozhang.ai/v1/images/generations
```

次の例は商品画像を作り、返ってきたファイル形式に応じて `generated.png`、`generated.jpg`、`generated.webp` のいずれかで保存します。

> [tab] cURL
>
> ```bash theme={null}
> curl --fail-with-body --max-time 360 \
>   "https://api.laozhang.ai/v1/images/generations" \
>   -H "Authorization: Bearer $LAOZHANG_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "model": "gpt-image-2.5-flare-vip",
>     "prompt": "白いテーブルに置かれた青いセラミックのカップ。やわらかな自然光、商品写真。"
>   }' \
>   -o generation-response.json
> ```
>
> リクエストが完了したら、`generation-response.json` から画像を保存します。
>
> ```bash theme={null}
> python save_images.py generation-response.json generated
> ```

> [tab] Python
>
> ```python theme={null}
> import os
> from openai import OpenAI
> from save_images import save_images
>
> client = OpenAI(
>     api_key=os.environ["LAOZHANG_API_KEY"],
>     base_url="https://api.laozhang.ai/v1",
>     timeout=360.0,
>     max_retries=0,
> )
> response = client.images.generate(
>     model="gpt-image-2.5-flare-vip",
>     prompt="白いテーブルに置かれた青いセラミックのカップ。やわらかな自然光、商品写真。",
> )
> save_images(response.model_dump(), "generated")
> ```

保存した画像を開いて結果を確認してください。`.json` ファイルにはAPIのレスポンスが入っています。拡張子を `.png` に変えても画像にはなりません。

## 画像を編集する

コマンドを実行するディレクトリに、`input.png` という名前の画像を置きます。ファイルと指示を、マルチパートのフォームデータとして次のエンドポイントに送ります。

```text theme={null}
POST https://api.laozhang.ai/v1/images/edits
```

次の例は背景を変え、結果を `edited.png`、`edited.jpg`、`edited.webp` のいずれかで保存します。

> [tab] cURL
>
> ```bash theme={null}
> curl --fail-with-body --max-time 360 \
>   "https://api.laozhang.ai/v1/images/edits" \
>   -H "Authorization: Bearer $LAOZHANG_API_KEY" \
>   -F "model=gpt-image-2.5-sunburst-vip" \
>   -F "image[]=@input.png" \
>   -F 'prompt=背景を淡い青に変えてください。被写体はそのままにしてください。' \
>   -o edit-response.json
> ```
>
> リクエストが完了したら、`edit-response.json` から画像を保存します。
>
> ```bash theme={null}
> python save_images.py edit-response.json edited
> ```

> [tab] Python
>
> ```python theme={null}
> import os
> from openai import OpenAI
> from save_images import save_images
>
> client = OpenAI(
>     api_key=os.environ["LAOZHANG_API_KEY"],
>     base_url="https://api.laozhang.ai/v1",
>     timeout=360.0,
>     max_retries=0,
> )
> with open("input.png", "rb") as source:
>     response = client.images.edit(
>         model="gpt-image-2.5-sunburst-vip",
>         image=[source],
>         prompt="背景を淡い青に変えてください。被写体はそのままにしてください。",
>     )
> save_images(response.model_dump(), "edited")
> ```

`image[]=@input.png` はファイルの中身をアップロードします。JSONにパスの文字列を書いても、ローカルのファイルはアップロードされません。cURLの `-F` を使うときは、マルチパートのContent-Typeと境界文字列はcURLに任せ、`Content-Type: application/json` を付けないでください。

変えたい内容と、残したい細部の両方を書いてください。画像の編集は生成によって行われるため、被写体をそのままにするよう指示しても、編集範囲の外のピクセルが完全に同じになるとは限りません。

## リクエストのオプション

上の最小限の例では、モデルの既定の出力設定を使っています。サイズや品質を選ぶには、[GPT Image 2.5](https://docs.laozhang.ai/ja/api-capabilities/gpt-image-2-5.md)か[GPT Image 2](https://docs.laozhang.ai/ja/api-capabilities/gpt-image-2.md)のページで、使うモデルのオプションを確認してください。

| フィールド | 用途 |
| - | - |
| `model` | 必須。`-vip` などの接尾辞を含むモデルID |
| `prompt` | 必須。画像の説明、または変更内容 |
| `image[]` | 編集では必須。マルチパートでアップロードするファイル |
| `size` | 任意。出力サイズ。使える値はモデルによって異なる |
| `quality` | 任意。品質の設定。使える値はモデルによって異なる |
| `n` | 任意。画像の枚数。モデルの上限に従う |

GPT ImageとDALL·Eでは、使えるオプションが違います。DALL·Eの `quality="hd"` や `style` を、GPT Imageのリクエストにそのまま持ち込まないでください。マスク、複数の参照画像、透過背景、出力形式の指定も、モデルごとの手順に従う必要があります。ローカルの画像を1枚編集するだけなら、上の基本的なファイルのアップロードを使ってください。

## 画像の結果を読み取る

`data[]` の各エントリーは出力画像1枚で、次の2つのどちらかの形で返ります。

* **`b64_json`**：Base64でエンコードされた画像のバイト列です。`data:image/...;base64,` の接頭辞が付いたり、末尾の `=` のパディングが欠けたりするレスポンスもあるため、`save_images.py` と同じように、接頭辞を取り除いてパディングを補ってからデコードします。
* **`url`**：ダウンロードリンクです。LaoZhang APIのキーを付けずにすぐ取得し、自分の手元に保存してください。URLの結果は期限切れになることがあります。

複数の画像を求めた場合は、`data[]` のすべてのエントリーを処理してください。画像生成のタスクIDや、Geminiの `candidates` のレスポンスは別の形式なので、それぞれのAPIに合った処理が必要です。

## エラーとリトライ

* **400：** リクエストのフィールドとモデルのオプションを確認します。編集では、ファイルがマルチパートでアップロードされていることを確認します。
* **401または403：** APIキー、トークングループ、モデルの権限を確認します。
* **404、またはモデルを利用できないというエラー：** コンソールの[モデルと料金](https://api.laozhang.ai/account/pricing)で、エンドポイントと正確なモデルIDを確認します。
* **429：** エラーの本文を読み、レート制限や同時実行の制限なのか、アカウントの残高の問題なのかを見分けます。
* **5xxまたはタイムアウト：** 画像のリクエストを再送する前に、[呼び出しログ](https://docs.laozhang.ai/en/faq/call-logs.md)を確認します。

クライアント側でタイムアウトしても、サーバー側の生成は取り消されません。Pythonの例ではSDKの自動リトライを無効にしているため、リクエストを繰り返すかどうかはアプリケーションで判断できます。

現在の料金と課金単位はコンソールに表示されます。サービスと返金の条件は[利用規約](https://www.laozhang.ai/terms)に定められています。

## 関連ドキュメント

* [API接続ガイド](https://docs.laozhang.ai/ja/api-manual.md)
* [画像APIの比較](https://docs.laozhang.ai/ja/api-capabilities/image-generation-guide.md)
* [Nano Bananaの概要](https://docs.laozhang.ai/ja/api-capabilities/nano-banana-image.md)
* [OpenAI image generation guide](https://developers.openai.com/api/docs/guides/image-generation)
* [OpenAI image editing reference](https://developers.openai.com/api/reference/resources/images/methods/edit)


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