GPT-Image-2 Image Generation | API Docs

gpt-image-2 supports image generation and reference-image editing for product images, poster drafts, illustrations, social assets, high-resolution visuals, style transfer, and multi-reference fusion.

text

POST https://api.requestbeam.com/openai/v1/images/generations

Authentication

http

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Quick Start

json

{
  "model": "gpt-image-2",
  "prompt": "A minimal black wireless earbud product poster on a white background, clean studio lighting, no text",
  "n": 1,
  "size": "2048x1152",
  "resolution": "2k",
  "quality": "low"
}

Body

modelstringrequiredDefault: gpt-image-2

Image model ID. Use gpt-image-2.

promptstringrequired

Image prompt. Describe the subject, scene, composition, style, material, lighting, colors, and whether text should appear.

nintegerDefault: 1

Number of images to generate. The current gpt-image-2 public contract only supports 1. Other values return 400 before reservation.

sizestringDefault: auto

Output aspect ratio or pixel dimensions.

Common values:

1:1
4:3
16:9
9:16
1024x1024
1536x1024
1024x1536
2048x2048
2048x1152
3840x2160
2160x3840
auto

qualitystringDefault: auto

Output quality. Supported values include low, medium, high, and auto.

resolutionstringDefault: 1k

Output resolution tier. Supported values are 1k, 2k, and 4k.

It can be combined with size, for example size: "16:9" and resolution: "2k".

image_urlsarray<string>

Reference images used for instruction-based editing or multi-image fusion.

Up to 16 images.
Each image can be up to 20 MB, with a 256 MB total input limit.
Publicly accessible image URLs are supported.
Base64 data URIs such as data:image/...;base64,... are supported.
URLs and base64 data URIs can be mixed in the same array.

output_formatstringDefault: png

Output format. Supported values include png, jpeg, and webp.

streambooleanDefault: false

Whether to return Server-Sent Events.

Reference Images And Editing

Reference-image editing uses the same JSON endpoint. Add image_urls and describe what to preserve and change in prompt:

json

{
  "model": "gpt-image-2",
  "prompt": "Keep the product unchanged, replace the background with a dark blue studio, and add soft rim lighting",
  "image_urls": [
    "https://example.com/product.png"
  ],
  "size": "1:1",
  "resolution": "2k"
}

Multiple references can provide the subject, composition, or visual style:

json

{
  "model": "gpt-image-2",
  "prompt": "Use the product from the first image and the composition from the second image to create a clean ecommerce hero image",
  "image_urls": [
    "https://example.com/product.png",
    "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
  ],
  "size": "4:3",
  "resolution": "2k"
}

Current public contract boundaries:

Whole-image editing, style transfer, and multi-reference fusion are supported through image_urls.
There is no separate POST https://api.requestbeam.com/openai/v1/images/edits route.
multipart/form-data uploads are not accepted. Convert local images to base64 data URIs or upload them to accessible URLs first.
Mask-based inpainting is unsupported. Sending mask, mask_url, or maskUrl returns 400 before reservation.

Request Examples

1:1 Product Image

json

{
  "model": "gpt-image-2",
  "prompt": "A transparent glass cup on a light gray background, commercial product photography, soft shadow, no text",
  "n": 1,
  "size": "1024x1024",
  "resolution": "1k",
  "quality": "low",
  "output_format": "png"
}

16:9 Poster

json

{
  "model": "gpt-image-2",
  "prompt": "A futuristic city night poster with neon lights, wet streets, cinematic composition, no text",
  "n": 1,
  "size": "2048x1152",
  "resolution": "2k",
  "quality": "medium",
  "output_format": "jpeg"
}

How Results Are Returned

This OpenAI-compatible endpoint does not first return a task submission response containing data.jobId for later polling:

With stream: false, the current HTTP request waits for completion and

returns image URLs in the JSON response.

With stream: true, the current SSE connection remains open through

image_generation.completed and [DONE].

Do not use GET https://api.requestbeam.com/v1/jobs/{id} to retrieve results from this endpoint. Use Get Async Job only when an asynchronous creation endpoint explicitly returns a jobId.

Non-Streaming Response

The response contains image URLs. usage is included when the upstream route provides metering information.

json

{
  "created": 1777270000,
  "data": [
    {
      "url": "https://image.example.com/generated/123456789012345678/0.png"
    }
  ],
  "usage": {
    "input_tokens": 20,
    "output_tokens": 1234,
    "total_tokens": 1254
  }
}

Streaming Response

text

event: image_generation.completed
data: {"type":"image_generation.completed","data":[{"index":0,"url":"https://image.example.com/generated/123456789012345678/0.png"}],"usage":{"input_tokens":20,"output_tokens":1234,"total_tokens":1254}}

data: [DONE]

Size Reference

Target Ratio	1K Recommended	2K Recommended	4K Recommended
`1:1`	`1024x1024`	`2048x2048`	Not recommended
`3:2`	`1536x1024`	`2048x1360`	Not recommended
`2:3`	`1024x1536`	`1360x2048`	Not recommended
`4:3`	`1024x768`	`2048x1536`	Not recommended
`3:4`	`768x1024`	`1536x2048`	Not recommended
`16:9`	`1536x864`	`2048x1152`	`3840x2160`
`9:16`	`864x1536`	`1152x2048`	`2160x3840`
`21:9`	`2016x864`	`2688x1152`	`3840x1648`
`9:21`	`864x2016`	`1152x2688`	`1648x3840`

Error Response

See Error Codes and Troubleshooting for the full code reference, protocol differences, and diagnostic steps.

json

{
  "code": 10000,
  "message": "prompt is required",
  "type": "api_error"
}

Common errors:

400: missing required parameters or unsupported parameter combination
401: authentication failed or API Key is incorrect
402: insufficient balance
404: model does not exist or is not enabled
429: rate limit exceeded
5xx: service temporarily unavailable or image generation failed