GPT-Image-2.5 Image Generation

• Asynchronous processing returns a task_id for status queries
• Supports text-to-image and image editing with up to 16 reference images
• Supports local inpainting with transparent PNG masks
• Supports 15 aspect ratios, exact pixel dimensions, and 1K / 2K / 4K resolution tiers
• Supports low / medium / high / xhigh / max quality levels

Request example

curl --request POST \
  --url https://api.openveer.com/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-image-2.5-flare",
    "prompt": "a cozy reading nook by a rainy window, warm lamp light, cinematic lighting",
    "size": "1:1",
    "resolution": "1k",
    "quality": "medium",
    "n": 1
  }'

import requests

response = requests.post(
    "https://api.openveer.com/v1/images/generations",
    headers={
        "Authorization": "Bearer <token>",
        "Content-Type": "application/json",
    },
    json={
        "model": "gpt-image-2.5-flare",
        "prompt": "a cozy reading nook by a rainy window, warm lamp light, cinematic lighting",
        "size": "1:1",
        "resolution": "1k",
        "quality": "medium",
        "n": 1,
    },
)

print(response.json())

const response = await fetch(
  "https://api.openveer.com/v1/images/generations",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer <token>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "gpt-image-2.5-flare",
      prompt: "a cozy reading nook by a rainy window, warm lamp light, cinematic lighting",
      size: "1:1",
      resolution: "1k",
      quality: "medium",
      n: 1,
    }),
  },
);

console.log(await response.json());

Response example

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01KXXXXXXXXXXXXXXX"
    }
  ]
}

{
  "error": {
    "code": 400,
    "message": "Invalid request parameters",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": 401,
    "message": "Authentication failed. Check your API key.",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": 402,
    "message": "Insufficient account balance",
    "type": "payment_required"
  }
}

{
  "error": {
    "code": 429,
    "message": "Too many requests. Try again later.",
    "type": "rate_limit_error"
  }
}

Authentication

Authorization: Bearer YOUR_API_KEY

Choose a model

The two models have identical token usage and pricing for the same parameters. Select one based on the speed-versus-quality tradeoff.

Compared with gpt-image-2, GPT-Image-2.5 adds the xhigh and max quality levels. Its medium and high levels use roughly one quarter of the output tokens of the previous generation's levels with the same names.

Request parameters

The mask guides editing, but the model does not guarantee that pixels outside the mask boundary remain completely unchanged.

Size rules

Exact pixel dimensions must satisfy all of these constraints:

• Width and height are both multiples of 16
• Neither side exceeds 3840 pixels
• Long-side to short-side ratio is at most 3:1
• Total pixel count is between 655,360 and 8,294,400

Aspect ratio and resolution mapping

You may also pass any exact dimensions that satisfy the size rules; they do not need to appear in this table.

Usage examples

Text to image

{
  "model": "gpt-image-2.5-flare",
  "prompt": "a sky garden in a futuristic city, morning mist, architectural photography",
  "size": "16:9",
  "resolution": "2k",
  "quality": "high",
  "n": 1
}

Precision editing with Sunburst

{
  "model": "gpt-image-2.5-sunburst",
  "prompt": "preserve the product and package text, replace the background with a soft off-white studio, and add a natural shadow",
  "image_urls": ["https://example.com/product.png"],
  "resolution": "2k",
  "quality": "xhigh"
}

Local inpainting with a mask

This example edits only the fully transparent area of the mask. The mask dimensions must match product.png:

{
  "model": "gpt-image-2.5-sunburst",
  "prompt": "replace only the area covered by the transparent mask with a gold ribbon, preserving the product and the rest of the background",
  "image_urls": [
    "https://example.com/product.png"
  ],
  "mask_url": "https://example.com/product-mask.png",
  "quality": "xhigh"
}

Transparent background

{
  "model": "gpt-image-2.5-flare",
  "prompt": "e-commerce product photo of white sneakers, complete subject, transparent background",
  "size": "1:1",
  "resolution": "2k",
  "quality": "high",
  "background": "transparent",
  "output_format": "png"
}

Submission and task query

Successful submission immediately returns an asynchronous task ID. data is an array; read data[0].task_id.

Call the task status endpoint with the returned ID. Poll every 2–5 seconds until the status becomes completed or failed. Use POST /v1/tasks/batch to query multiple tasks.

{
  "code": 200,
  "data": {
    "id": "task_01KXXXXXXXXXXXXXXX",
    "status": "completed",
    "progress": 100,
    "cost": 0.01325,
    "credits_cost": 0.1325,
    "result": {
      "images": [
        {
          "url": ["https://upload.openveer.com/f/image/example.png"],
          "expires_at": 1789000000
        }
      ]
    },
    "usage": {
      "input_tokens": 16,
      "output_tokens": 439,
      "total_tokens": 455
    }
  }
}

Image URLs are located at data.result.images[].url[]. Download and store them promptly instead of relying on temporary URLs.

Billing

GPT-Image-2.5 is billed by actual token usage. Flare and Sunburst use identical rates. Check the pricing page or /api/pricing for current account pricing.

1024×1024 output token reference

For n > 1, the reservation scales linearly with the requested image count. Final billing uses the number of images actually generated, and failed tasks are refunded automatically.

Output token reference

Values are per generated image. Actual billing also includes prompt and reference-image input tokens.

Limits and common errors

Response

This documentation is built and hosted on Mintlify, a developer documentation platform.