GPT Image synchronous Call
GPT Image models support general image generation and editing, including product images, marketing posters, social media, reference-based changes, background replacement and detailed edits. Common models include gpt-image-2, gpt-image-2-pro and gpt-image-2-vip. Use the current model ID from the console, pricing page or GET /v1/models.
This page covers synchronous requests, which keep the HTTP connection open until generation or editing finishes. For long tasks, see GPT Image asynchronous requests.
gpt-image-* does not recommend the generation of pictures through /v1/chat/completions. Please submit a picture to or edit request using the Images API portal; chat to complete API is used mainly for dialogue text and visual understanding type models and is not used as a steady image generation portal for GPT Image.
synchronous entrance
| Capacity | Path | Annotations |
|---|---|---|
| Picture Generation | /v1/images/generations | Generates pictures from text prompt and returns the result directly. |
| Picture Editor | /v1/images/edits | Default to upload pictures using multipart; some API Key groups also support JSON images URL. |
| Picture variant | /v1/images/variations | Models are supported by generating a comparable version based on the original map. |
Model selection
| Models | Recommended use | Dimension Call |
|---|---|---|
gpt-image-2 | Generic text-to-image, conventional media assets, sketches and creative maps. | size may be passed aspect ratio or 1K pixels. |
gpt-image-2-pro | Increased emphasis on quality, detail and editing of photos task. | Same as gpt-image-2-vip, size transfers 1K to 4K pixels. |
gpt-image-2-vip | Use when higher priority or more specification size is required. | Same as gpt-image-2-pro, size transfers 1K to 4K pixels. |
synchronous Photo Generation
curl https://moonnexai.com/v1/images/generations \
-H "Authorization: Bearer <MOONNEXAI_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2",
"prompt": "A clean product mockup on a white studio table.",
"size": "1024x1024",
"n": 1
}'Generate field
| field | Annotations |
|---|---|
model | Always. Model names, such as gpt-image-2, gpt-image-2-pro or gpt-image-2-vip. |
prompt | It is. Picture description, suggesting that the main subject, scene, style, structure, aspect ratio and use be written. |
size | Optional. Output size. gpt-image-2 can pass aspect ratio or 1K pixel values; gpt-image-2-pro and gpt-image-2-vip pass pixel values. |
n | Optional. Generate the quantity, which is based on the model and the range of account available. |
response_format | Optional. Common url or b64_json, based on API Reference. |
Photo Editor for synchronous
Multipart file upload is the default call:
curl https://moonnexai.com/v1/images/edits \
-H "Authorization: Bearer <MOONNEXAI_API_KEY>" \
-F "image=@./product.png" \
-F "model=gpt-image-2-pro" \
-F "prompt=Change the background to a clean studio scene." \
-F "size=1024x1024"In addition to multipart uploads, some API key groups accept image URLs in application/json on synchronous endpoints. JSON URL support, single or multiple images and image-count limits depend on your key's group and selected model. Do not assume all groups accept identical inputs.
Synchronous request with one image URL:
curl https://moonnexai.com/v1/images/edits \
-H "Authorization: Bearer <MOONNEXAI_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2",
"prompt": "保留商品主体，把背景改成干净的摄影棚场景。",
"image": "https://example.com/product.png",
"size": "1024x1024",
"n": 1
}'image can be passed to URL arrays when currently grouping and modeling supports multigraphs:
{
"model": "gpt-image-2",
"prompt": "保留第一张图的主体，参考第二张图的色彩和细节。",
"image": [
"https://example.com/subject.png",
"https://example.com/style.png"
],
"size": "1024x1024",
"n": 1
}JSON URL should use a stable HTTPS photo address without login, without request headers and directly downloadable from the public network.
Edit field
| field | Annotations |
|---|---|
image | It is. Default transfer multipart picture files; some API Key groups also support a JSON image URL or URL array, which is based on grouping and modeling capabilities. |
mask | Optional. The masked file used for local changes is supported by API Reference. |
model | It is necessary to fill. It is recommended that high-quality editing be processed using gpt-image-2-pro or gpt-image-2-vip. |
prompt | It is. Writes the content to be retained, the area to be modified and the target effect. |
size | Optional. Output size, gpt-image-2-pro and gpt-image-2-vip support the same pixel values. |
Size and aspect ratio
gpt-image-2 supports the direct transmission of aspect ratio, such as 16:9, and can also pass 1K pixel values. Common values are as follows:
| aspect ratio | Example size |
|---|---|
auto | auto |
1:1 | 1024x1024 |
16:9 | 16:9 or 1672x941 |
9:16 | 9:16 or 941x1672 |
4:3 | 4:3 or 1443x1090 |
3:4 | 3:4 or 1090x1443 |
3:2 | 3:2 or 1536x1024 |
2:3 | 2:3 or 1024x1536 |
5:4 | 5:4 or 1408x1120 |
4:5 | 4:5 or 1120x1408 |
21:9 | 21:9 or 1920x832 |
9:21 | 9:21 or 832x1920 |
2:1 | 2:1 or 1792x896 |
1:2 | 1:2 or 896x1792 |
gpt-image-2-pro and gpt-image-2-vip have the same sizes, and size pixel values are passed without aspect ratio. Supports the usual sizes of 1K, 2K, 4K, and supports the custom pixel values that satisfy the constraints.
| aspect ratio | 1K | 2K | 4K |
|---|---|---|---|
auto | auto | auto | auto |
1:1 | 1024x1024 | 2048x2048 | 2880x2880 |
16:9 | 1280x720 | 2048x1152 | 3840x2160 |
9:16 | 720x1280 | 1152x2048 | 2160x3840 |
4:3 | 1152x864 | 2304x1728 | 3264x2448 |
3:4 | 864x1152 | 1728x2304 | 2448x3264 |
3:2 | 1536x1024 | 2048x1360 | 3504x2336 |
2:3 | 1024x1536 | 1360x2048 | 2336x3504 |
5:4 | 1120x896 | 2240x1792 | 3200x2560 |
4:5 | 896x1120 | 1792x2240 | 2560x3200 |
21:9 | 1456x624 | 2912x1248 | 3840x1648 |
9:21 | 624x1456 | 1248x2912 | 1648x3840 |
3:1 | 2048x688 | - | 3840x1280 |
1:3 | 688x2048 | - | 1280x3840 |
2:1 | 1536x768 | 3072x1536 | 3840x1920 |
1:2 | 768x1536 | 1536x3072 | 1920x3840 |
Custom pixel values need to be met simultaneously:
- The maximum edge does not exceed
3840px. - The width and height must be a multiple of
16. - The longer side must not exceed three times the shorter side (
3:1). - Total pixels are not less than
655360and not more than8294400.
synchronous returns
{
"created": 1711234567,
"data": [
{
"url": "https://example.com/images/generated-image.png",
"revised_prompt": "A clean product photo on a white background."
}
]
}Recommendations addressed:
- Prefer to the
dataarray, not just to determine whether a URL field exists. - When
response_formatisurl, savedata[].url, model name, prompt, size and business order numbers. - When
response_formatisb64_json, writedata[].b64_jsonto your object for storage, and then save an accessible address in the repository. - If API returns HTTP error, the response, request parameter and business request ID are recorded to correct the prompt, photo format or size before retrying.
Prompt Recommendations
- Commodity chart: Writes the main commodity, background, light, lens angle, whether or not to retain the packaging text.
- Posters: Write for use, main vision, layout, white position and text area, and do not stuff a large number of files into prompt.
- reference images Editor: To clarify what must be retained and what needs to be replaced, so as to avoid simply saying “optimize”.
- Fixed aspect ratio output: Writes images aspect ratio and
size, for example, Prompt writes "Darver 9:16 poster",sizepass720x1280.