What’s new

Reference images: only PNG, JPEG, and WebP

GIF and BMP files are no longer accepted, either on upload through POST /uploads or by link in image_urls. Such a request gets 400 ERR_INVALID_REQUEST with the text “Unsupported image format. Supported formats: PNG, JPEG, WebP.” before the charge.

• The format is determined by the contents of the file, not by its extension.
• ICO has not been accepted since October 1.
• Files you uploaded earlier are not affected.

The upscaling and background-removal endpoints were removed

The POST /images/upscale and POST /images/remove-background endpoints no longer exist: requests to them get 404, like any unknown address.

Nano Banana 2.1 in the API

The newest Google model in the Nano Banana line: a realistic image, precise prompt following, consistent characters, and sharp text.

• 1K, 2K, and 4K resolutions. If you omit the resolution, it is 2K.
• Fifteen aspect_ratio values: ten regular ratios, the elongated 1:4, 4:1, 1:8, and 8:1, and auto.
• Up to 14 reference images in one request.

An empty prompt is declined before the charge

A generation request without a prompt (the field is missing, null, an empty string, or only spaces) gets 400 ERR_INVALID_REQUEST. details.fields shows which field is not filled in. No money is charged for such a request.

{
  "error": {
    "code": "ERR_INVALID_REQUEST",
    "message": "A prompt is required. Describe the image to generate in the prompt.",
    "details": { "fields": ["prompt"] }
  }
}

Statuses 422 and 500 for two error codes

Two error codes now have their own HTTP statuses. No API error code answers with the statuses 502 and 504.

• 422 ERR_INPUT_FETCH_FAILED—the reference image could not be downloaded or checked. The request is not charged.
• 500 ERR_GENERATION_FAILED—generation could not be started or completed. The charged amount is refunded automatically.

GPT Image 2.5 Sunburst and Flare at 1K, 2K, and 4K

Two models in the GPT Image 2.5 line for high-resolution images. Both work at 1K, 2K, and 4K and support eight aspect ratios.

• You choose the model in the model field and the resolution in the resolution field. If you omit the resolution, it is 1K.
• GPT Image 2.5 Sunburst stands out for precise work with details.

The failure field in failed tasks

Next to the error text, a failed task now has a failure object, both in the task polling response and in the creation.failed webhook. It shows whether the request was declined (declined) or failed (error), and whether a retry is worthwhile (retryable).

"failure": { "type": "declined", "code": "content_policy", "retryable": false }