Images API: generate and edit images

Create images from text, or upload an image and describe the changes. Both endpoints use the OpenAI Images response format.

Item	Details
Generate	`POST /v1/images/generations`
Edit	`POST /v1/images/edits`
Results	Each image in `data[]`, as either `b64_json` or a `url`
Example model	`gpt-image-2-vip`

For Gemini-native image generation and editing with Nano Banana models, see the Nano Banana API overview. To compare image models and endpoints, see Choose an image API.

Set up your credentials

Create a model API key in Token management and make it available as the LAOZHANG_API_KEY environment variable. Check that its group has access to gpt-image-2-vip in Models and pricing. Set the key in your terminal, replacing the placeholder:

export LAOZHANG_API_KEY="YOUR_LAOZHANG_API_KEY"

The examples below use:

API host: https://api.laozhang.ai
OpenAI SDK base URL: https://api.laozhang.ai/v1
Authentication: Authorization: Bearer $LAOZHANG_API_KEY
Model: gpt-image-2-vip

Install the Python packages used to call the API and save images. The cURL examples also use Python to decode the response and choose the correct file extension.

python -m pip install openai pillow httpx

Save images from a response

Save this helper as save_images.py in the directory where you run the examples. It writes every image in data[] to disk, whether the entry holds b64_json or a url:

"""Save every image in an OpenAI Images API response."""
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):
    """Return the image bytes of one data[] entry."""
    encoded = item.get("b64_json")
    if encoded:
        encoded = "".join(encoded.split())
        if encoded.startswith("data:"):
            encoded = encoded.split(",", 1)[1]  # drop a data:image/...;base64, prefix
        encoded += "=" * (-len(encoded) % 4)  # restore missing padding
        return base64.b64decode(encoded)
    if item.get("url"):
        # Download the result without sending your LaoZhang API key.
        download = httpx.get(item["url"], timeout=120, follow_redirects=True)
        download.raise_for_status()
        return download.content
    raise ValueError("The data[] entry contains neither b64_json nor url")


def save_images(response, stem):
    """Save each image as <stem>.<ext>, then <stem>-2.<ext>, and so on."""
    entries = response.get("data") or []
    if not entries:
        raise RuntimeError(f"The response contains no images: {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"Saved {output} ({size})")


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

Run it as python save_images.py <response.json> <name> after a cURL request, or import save_images in Python.

Generate an image

Send a JSON body containing model and prompt to:

POST https://api.laozhang.ai/v1/images/generations

These examples create a product image and save it as generated.png, generated.jpg, or generated.webp, according to the returned file format.

cURL
Python

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": "A blue ceramic cup on a white table, soft natural light, product photography."
  }' \
  -o generation-response.json

After the request completes, save the image from generation-response.json:

python save_images.py generation-response.json generated

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-vip",
    prompt="A blue ceramic cup on a white table, soft natural light, product photography.",
)
save_images(response.model_dump(), "generated")

Open the saved image to see the result. The .json file contains the API response; changing its extension to .png does not convert it into an image.

Edit an image

Place an image named input.png in the directory where you run the command. Send the file and your instructions as multipart form data to:

POST https://api.laozhang.ai/v1/images/edits

The examples below change the background and save the result as edited.png, edited.jpg, or edited.webp.

cURL
Python

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=Change the background to pale blue. Keep the subject unchanged.' \
  -o edit-response.json

After the request completes, save the image from edit-response.json:

python save_images.py edit-response.json edited

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-vip",
        image=[source],
        prompt="Change the background to pale blue. Keep the subject unchanged.",
    )
save_images(response.model_dump(), "edited")

image[]=@input.png uploads the file contents. A plain path string in JSON does not upload a local file. When using cURL’s -F option, let cURL set the multipart content type and boundary; do not add Content-Type: application/json. Describe both the change you want and the details to preserve. Image editing is generative, so an instruction to keep the subject unchanged does not guarantee identical pixels outside the edited area.

Request options

The minimal examples use the model’s default output settings. To choose dimensions or quality, use the options listed for the exact model in the GPT Image 2 guide or GPT Image 2.5 guide.

Field	Purpose
`model`	Required model ID, including any suffix such as `-vip`.
`prompt`	Required description of the image or requested changes.
`image[]`	Required file upload for the multipart edit operation.
`size`	Optional output dimensions; accepted values depend on the model.
`quality`	Optional quality setting; values depend on the model.
`n`	Optional image count, subject to the model’s limits.

GPT Image and DALL·E use different options. Do not copy DALL·E’s quality="hd" or style into a GPT Image request. Masks, multiple reference images, transparent backgrounds, and output-format controls also require model-specific instructions; use the basic file upload above when editing a single local image.

Read image results

Each entry in data[] is one output image, returned in one of two forms:

b64_json holds the Base64-encoded image bytes. Some responses add a data:image/...;base64, prefix or drop the trailing = padding, so strip the prefix and restore the padding before decoding, as save_images.py does.
url is a download link. Fetch it promptly without your LaoZhang API key and keep your own copy; URL results may expire.

When requesting more than one image, process every entry in data[]. An image-generation task ID or a Gemini candidates response uses a different format and needs the handler for that API.

Errors and retries

400: check the request fields and model options. For edits, confirm that the file was uploaded as multipart data.
401 or 403: check the API key, token group, and model permissions.
404 or an unavailable-model error: check the endpoint and exact model ID in Models and pricing.
429: read the error body to distinguish rate or concurrency limits from account balance issues.
5xx or timeout: inspect call logs before submitting the image request again.

A client timeout does not cancel server-side generation. The Python examples disable automatic SDK retries so that your application can decide whether to repeat a request. Current prices and billing units are shown in the console; service and refund terms are covered by the Terms.

Core APIs

Other APIs

Images API: generate and edit images

Set up your credentials

Save images from a response

Generate an image

Edit an image

Request options

Read image results

Errors and retries

​Set up your credentials

​Save images from a response

​Generate an image

​Edit an image

​Request options

​Read image results

​Errors and retries

​Related documentation

Set up your credentials

Save images from a response

Generate an image

Edit an image

Request options

Read image results

Errors and retries

Related documentation