Generate or edit one image with the GPT Image 2 API

xplaai exposes the standard GPT Image 2 API contract through POST /v1/images/generations. It supports synchronous text-to-image and reference-image editing, one generated image per request, documented ratio or pixel-size values, optional quality and JSON output. Use size or aspectRatio, keep replyType as JSON, and do not send imageSize.

Create an API key or review the current image documentation.

GPT Image 2 contract at a glance

The endpoint returns an xplaai-hosted content URL that requires API authentication. Treat it as result delivery, not permanent public storage.

Create a text-to-image request

export XPLA_API_KEY="your_api_key"

curl --request POST \
  --url https://xplaai.com/v1/images/generations \
  --header "Authorization: Bearer $XPLA_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "gpt-image-2",
    "prompt": "a clean studio product image on a warm neutral background with soft directional lighting",
    "images": [],
    "aspectRatio": "1024x1024",
    "quality": "auto",
    "replyType": "json",
    "n": 1
  }'

For text-to-image, omit the reference field or pass an empty array. Keep the API key on the server side.

Edit a reference image

Pass one or more supported reference-image values through images:

{
  "model": "gpt-image-2",
  "prompt": "preserve the product shape and label, replace the background with a clean green technology studio",
  "images": [
    "https://example.com/product-reference.png"
  ],
  "aspectRatio": "1536x1024",
  "quality": "high",
  "replyType": "json",
  "n": 1
}

The reference URL must be reachable when the request is processed. When base64 input is used, validate its media type and size before submission. Do not put credentials in a media URL.

Choose a ratio or explicit pixel value

The standard model accepts documented ratio values including:

• auto;
• 1:1, 16:9 and 9:16;
• 4:3 and 3:4;
• 3:2 and 2:3;
• 5:4 and 4:5;
• 21:9 and 9:21;
• 1:2 and 2:1.

It also accepts documented pixel values such as 1024x1024, 1536x1024 or 1792x896.

Use either size or aspectRatio as the application-level control. If both are accepted by a client, prevent conflicting values before the request reaches xplaai.

Keep imageSize out of the standard request

imageSize belongs to separately named image contracts such as gpt-image-2-medium. The standard gpt-image-2 model should reject it.

This distinction matters because the GPT Image 2 names are not interchangeable:

Choose the exact public model and validate only its fields. A similar name is not an invitation to mix parameters or expect an invisible fallback.

Generate one image per request

Use n: 1 and create separate requests when your application needs several candidates. This makes task accounting, retries and result storage explicit.

Avoid retrying a completed request simply because the client lost the response. Persist your application request state and distinguish transport retries from an intentional new generation.

Handle the authenticated image response

A successful synchronous request uses an OpenAI-compatible image-response shape:

{
  "created": 1718600000,
  "data": [
    {
      "url": "https://xplaai.com/v1/videos/task_xxx/content"
    }
  ]
}

The URL is an authenticated xplaai content address. Your application should:

1. retrieve it with authorized access;
2. move the asset into storage that matches your retention policy;
3. avoid placing the URL or API key in public logs;
4. store the public model name and request options with the asset;
5. apply any human review required before publishing.

Use GPT Image 2 inside a larger workflow

The API is useful when your application owns the prompt, references, review process and storage. A generated image can then become an input to the AI video API or the Veo 3.1 Fast API.

For a packaged workflow that combines product information, creative assets and short-form output, explore xplaai Commerce Skills.

Frequently asked questions

Is GPT Image 2 synchronous?

The standard gpt-image-2 contract is synchronous through /v1/images/generations. The separately named gpt-image-2-1K model uses an asynchronous task contract.

Can I edit a reference image?

Yes. Pass supported reference URLs or base64 values through image or images and describe the intended edit in the prompt.

Which aspect ratios are supported?

The standard model accepts documented ratios such as 1:1, 16:9, 9:16, 4:3, 3:4, 3:2 and 2:3, plus additional listed ratios and explicit pixel values.

Can I request more than one image?

Use one image per request and set n: 1. Submit separate requests when you need multiple candidates.

Should I use imageSize?

No. imageSize is not part of the standard gpt-image-2 contract. Use size or aspectRatio.

Is the result URL permanent and public?

Do not assume so. It is an authenticated xplaai content address. Retrieve the asset and store it according to your application's policy.

Copy the GPT Image 2 example

Create an xplaai API key, copy the text-to-image request above and test one image before adding reference editing or production storage.