> ## 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：图片生成与编辑

> 通过老张API生成图片或上传参考图进行编辑，使用 cURL 与 OpenAI Python SDK 发送请求，并将 Base64 或 URL 响应保存为图片。

Images API 用于根据文字生成图片，或修改已有图片。生成与编辑两个接口都返回 `data` 数组，可以用同一段代码保存图片。

| 项目 | 内容 |
| - | - |
| 生成图片 | `POST /v1/images/generations` |
| 编辑图片 | `POST /v1/images/edits` |
| 响应 | `data` 数组，保存方法见[保存返回图片](#保存返回图片) |
| 本页示例模型 | `gpt-image-2-vip`，分别提供生成和编辑的完整请求 |

Gemini 原生图片接口采用不同的请求与响应格式，Nano Banana 系列的接入方式见 [Nano Banana API 总览](/api-capabilities/nano-banana-image)。

## 配置密钥与依赖

在[令牌管理](https://api.laozhang.ai/token)创建 API Key，并在[模型与价格](https://api.laozhang.ai/account/pricing)确认令牌分组可以调用 `gpt-image-2-vip`。将密钥设置为服务端环境变量：

```bash theme={null}
export LAOZHANG_API_KEY="替换为你的老张API密钥"
python -m pip install openai pillow
```

下文示例使用：

* 请求主机：`https://api.laozhang.ai`
* 认证头：`Authorization: Bearer $LAOZHANG_API_KEY`
* OpenAI Python SDK 的 `base_url`：`https://api.laozhang.ai/v1`

以下 cURL 和 Python 示例都将响应写入 JSON 文件，再由[保存返回图片](#保存返回图片)中的脚本提取图片。每个操作任选一种请求方式即可。

## 生成图片

**`POST /v1/images/generations`** 使用 JSON 请求体，必需字段是 `model` 和 `prompt`。`prompt` 描述希望生成的内容，无需提供输入图片。

<Tabs>
  <Tab title="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-vip",
        "prompt": "一只蓝色陶瓷杯放在白色桌面上，柔和的自然光，简洁的产品摄影。"
      }' \
      -o generation-response.json
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    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=360.0,
        max_retries=0,
    )
    response = client.images.generate(
        model="gpt-image-2-vip",
        prompt="一只蓝色陶瓷杯放在白色桌面上，柔和的自然光，简洁的产品摄影。",
    )
    Path("generation-response.json").write_text(
        response.model_dump_json(), encoding="utf-8"
    )
    print("响应已保存到 generation-response.json")
    ```
  </Tab>
</Tabs>

请求结束后，运行下方保存脚本，将 `generation-response.json` 转为可以打开的图片文件。

## 编辑图片

**`POST /v1/images/edits`** 使用 `multipart/form-data` 上传图片文件，同时发送 `model` 和 `prompt`。

把要编辑的 PNG 图片命名为 `input.png`，放在执行命令的目录中。

提示词应同时写清需要修改和希望保留的内容。下面将背景改为浅蓝色，并要求保留主体。

<Tabs>
  <Tab title="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-vip" \
      -F "image[]=@input.png" \
      -F "prompt=把背景改为浅蓝色，保留主体的外观和位置。" \
      -o edit-response.json
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    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=360.0,
        max_retries=0,
    )
    with open("input.png", "rb") as source:
        response = client.images.edit(
            model="gpt-image-2-vip",
            image=[source],
            prompt="把背景改为浅蓝色，保留主体的外观和位置。",
        )
    Path("edit-response.json").write_text(
        response.model_dump_json(), encoding="utf-8"
    )
    print("响应已保存到 edit-response.json")
    ```
  </Tab>
</Tabs>

上传文件时注意：

* `image[]=@input.png` 会上传文件内容；只传字符串 `input.png` 不会上传图片。
* 使用 cURL 的 `-F` 时，让 cURL 自动设置 `Content-Type` 和 multipart boundary，不要另加 `application/json`。
* Python SDK 使用 `image` 参数传入打开的文件。

## 保存返回图片

响应的 `data[]` 包含图片结果，常见字段如下：

| 字段 | 说明 |
| - | - |
| `b64_json` | Base64 编码的图片内容 |
| `url` | 图片下载地址 |

下面的脚本能处理这两种字段：

* `b64_json` 可能带 `data:image/png;base64,` 这类前缀，也可能缺少末尾的 `=` 填充；脚本解码前先去掉前缀并补齐填充。
* `url` 会过期，收到响应后请尽快下载；脚本遇到 `url` 会立即下载。

JSON 文件是响应数据，不能通过修改扩展名变成图片。

将以下代码保存为 `save_images.py`。脚本会读取全部图片结果，识别实际格式，并打印保存路径和尺寸。依赖已在前面通过 `pillow` 安装。

```python theme={null}
import base64
import io
import json
import sys
import urllib.request
from pathlib import Path
from PIL import Image

if len(sys.argv) != 3:
    raise SystemExit("用法：python save_images.py 响应文件.json 输出文件前缀")


def decode_b64(value):
    # 去掉可能存在的 data:image/...;base64, 前缀，并补齐缺失的 = 填充
    if value.startswith("data:"):
        value = value.split(",", 1)[1]
    value = "".join(value.split())
    value += "=" * (-len(value) % 4)
    return base64.b64decode(value, validate=True)


response_path = Path(sys.argv[1])
output_prefix = sys.argv[2]
payload = json.loads(response_path.read_text(encoding="utf-8"))
if payload.get("error"):
    raise RuntimeError(payload["error"])
items = payload.get("data") or []
if not items:
    raise RuntimeError("响应中没有图片结果，请检查错误信息和调用日志")

for index, item in enumerate(items, start=1):
    if item.get("b64_json"):
        raw = decode_b64(item["b64_json"])
    elif item.get("url"):
        with urllib.request.urlopen(item["url"], timeout=60) as download:
            raw = download.read()
    else:
        raise RuntimeError(f"第 {index} 项缺少图片内容或下载地址")

    with Image.open(io.BytesIO(raw)) as picture:
        picture.load()
        extension = {"PNG": "png", "JPEG": "jpg", "WEBP": "webp"}.get(
            picture.format
        )
        if extension is None:
            raise RuntimeError(f"无法保存图片格式：{picture.format}")
        output = Path(f"{output_prefix}-{index}.{extension}")
        output.write_bytes(raw)
        print(f"已保存 {output}，尺寸 {picture.width} × {picture.height}")
```

生成请求结束后执行：

```bash theme={null}
python save_images.py generation-response.json generated
```

编辑请求结束后执行：

```bash theme={null}
python save_images.py edit-response.json edited
```

输出文件名类似 `generated-1.png` 或 `edited-1.png`，扩展名由实际图片格式决定。打开文件查看生成内容或编辑效果。下载响应中的 URL 时不需要附带老张API密钥。

## 尺寸、质量与其他参数

先用必需字段完成请求，再按目标模型的说明添加参数。同为 Images 接口，不同模型接受的参数和值也可能不同。

| 参数 | 用途与限制 |
| - | - |
| `size` | 输出尺寸；可选值以对应模型说明为准 |
| `quality` | 输出质量；不要把 DALL·E 的 `hd` 值用于 GPT Image |
| `n` | 图片数量；受模型和分组限制 |
| `output_format` | 输出格式；仅在模型支持时设置 |

`style` 和 `response_format` 也不是所有图像模型的通用参数。精确尺寸、透明背景、多图输入及遮罩等需求，请查看 [GPT Image 2 模型说明](/api-capabilities/gpt-image-2)或 [GPT Image 2.5 模型说明](/api-capabilities/gpt-image-2-5)，确认所用模型与分组的调用要求。

本页编辑示例上传本地图片文件。不要将其改成带有 `images`、`image_url` 或 `file_id` 的 JSON 请求；这属于另一种输入方式，需要对应接口明确支持。

## 请求失败时

* **400**：检查必需字段、图片文件是否存在，以及参数是否适用于当前模型。上传文件时尤其要检查请求的 `Content-Type`。
* **401 / 403**：检查 API Key 是否有效、令牌分组及模型权限。
* **404 / 503**：查看错误正文，核对接口路径、完整模型 ID 和分组；“无可用渠道”需要检查模型当前可用状态。
* **429 / 5xx / 超时**：查看[调用日志](/faq/call-logs)，确认请求状态后再决定是否重试。
* **收到响应但没有图片**：检查 `error`、`data`、Base64 内容或下载地址，不要把错误 JSON 当作图片保存。

图片请求可能耗时较长。客户端超时不表示服务端已经停止处理，立即重复提交可能产生额外请求。示例关闭了 SDK 自动重试，便于应用自行决定重试时机。

## 相关文档

* [OpenAI 图像生成指南](https://developers.openai.com/api/docs/guides/image-generation)
* [OpenAI 图片编辑接口参考](https://developers.openai.com/api/reference/resources/images/methods/edit)
* [API 开发文档](/api-manual)
* [模型与价格总表](/models)

实际价格与计费单位以当前分组和调用日志为准，服务及退款条款见[用户协议](https://www.laozhang.ai/zh-cn/terms)。


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