Images API: generate and edit images

Create images with POST /v1/images/generations, or upload an image and describe the changes with POST /v1/images/edits. Both endpoints use the OpenAI Images response format, with results in data[]. For Gemini image models and other image 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://api2.laozhang.ai
OpenAI SDK base URL: https://api2.laozhang.ai/v1
Authentication: Authorization: Bearer $LAOZHANG_API_KEY
Model: gpt-image-2-vip

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

python -m pip install openai pillow

Generate an image

Send a JSON body containing model and prompt to:

POST https://api2.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://api2.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, decode the image in generation-response.json:

python - <<'PY'
import base64
import io
import json
from pathlib import Path
from PIL import Image

response = json.loads(Path("generation-response.json").read_text())
raw = base64.b64decode(response["data"][0]["b64_json"], validate=True)
with Image.open(io.BytesIO(raw)) as image:
    image.load()
    extension = {"PNG": "png", "JPEG": "jpg", "WEBP": "webp"}[image.format]
    output = Path(f"generated.{extension}")
    output.write_bytes(raw)
    print(f"Saved {output} ({image.width} × {image.height})")
PY

import base64
import io
import os
from pathlib import Path
from openai import OpenAI
from PIL import Image

client = OpenAI(
    api_key=os.environ["LAOZHANG_API_KEY"],
    base_url="https://api2.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.",
)
if not response.data or not response.data[0].b64_json:
    raise RuntimeError("The response did not contain a Base64 image")
raw = base64.b64decode(response.data[0].b64_json, validate=True)
with Image.open(io.BytesIO(raw)) as image:
    image.load()
    extension = {"PNG": "png", "JPEG": "jpg", "WEBP": "webp"}[image.format]
    output = Path(f"generated.{extension}")
    output.write_bytes(raw)
    print(f"Saved {output} ({image.width} × {image.height})")

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://api2.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://api2.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 - <<'PY'
import base64
import io
import json
from pathlib import Path
from PIL import Image

response = json.loads(Path("edit-response.json").read_text())
raw = base64.b64decode(response["data"][0]["b64_json"], validate=True)
with Image.open(io.BytesIO(raw)) as image:
    image.load()
    extension = {"PNG": "png", "JPEG": "jpg", "WEBP": "webp"}[image.format]
    output = Path(f"edited.{extension}")
    output.write_bytes(raw)
    print(f"Saved {output} ({image.width} × {image.height})")
PY

import base64
import io
import os
from pathlib import Path
from openai import OpenAI
from PIL import Image

client = OpenAI(
    api_key=os.environ["LAOZHANG_API_KEY"],
    base_url="https://api2.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.",
    )
if not response.data or not response.data[0].b64_json:
    raise RuntimeError("The response did not contain a Base64 image")
raw = base64.b64decode(response.data[0].b64_json, validate=True)
with Image.open(io.BytesIO(raw)) as image:
    image.load()
    extension = {"PNG": "png", "JPEG": "jpg", "WEBP": "webp"}[image.format]
    output = Path(f"edited.{extension}")
    output.write_bytes(raw)
    print(f"Saved {output} ({image.width} × {image.height})")

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[] represents an output image. The gpt-image-2-vip examples above read b64_json, which contains Base64-encoded image bytes without a data: prefix. Other models may return url instead. If an entry contains a download URL, fetch it promptly and save the downloaded bytes. Do not include your LaoZhang API key in that download request. URL results may expire; keep your own copy of images your application needs to retain. When requesting more than one image, process every entry in data[]. An image-generation task ID or 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

Model Guides

Images API: generate and edit images

Set up your credentials

Generate an image

Edit an image

Request options

Read image results

Errors and retries

​Set up your credentials

​Generate an image

​Edit an image

​Request options

​Read image results

​Errors and retries

​Related documentation

Set up your credentials

Generate an image

Edit an image

Request options

Read image results

Errors and retries

Related documentation