Appearance
GPT Image 同步调用
GPT Image 系列用于通用图片生成和图片编辑，适合产品图、营销海报、社媒素材、参考图改写、背景替换和画面细节重绘。MoonNexAI 价格页当前常见模型包括 gpt-image-2、gpt-image-2-pro 和 gpt-image-2-vip。请求时请以 MoonNexAI 后台、价格页或 GET /v1/models 返回的模型名为准。
本页只说明同步调用。同步接口会保持当前 HTTP 连接，等待图片生成或编辑完成后直接返回结果。长耗时任务请使用独立的 GPT Image 异步调用 页面。
gpt-image-* 不推荐通过 /v1/chat/completions 生成图片。请使用 Images API 入口提交图片生成或编辑请求；聊天补全接口主要用于对话文本和视觉理解类模型，不作为 GPT Image 的稳定图片生成入口。
同步入口
| 能力 | 路径 | 说明 |
|---|---|---|
| 图片生成 | /v1/images/generations | 从文本 prompt 生成图片并直接返回结果。 |
| 图片编辑 | /v1/images/edits | 默认使用 multipart 上传图片；部分 API Key 分组也支持 JSON 图片 URL。 |
| 图片变体 | /v1/images/variations | 模型支持时基于原图生成相近版本。 |
模型选择
| 模型 | 建议用途 | 尺寸调用 |
|---|---|---|
gpt-image-2 | 通用文生图、常规素材生成、草图和创意图。 | size 可传比例值或 1K 像素值。 |
gpt-image-2-pro | 更重视质量、细节和编辑稳定性的图片任务。 | 与 gpt-image-2-vip 相同，size 传 1K 到 4K 像素值。 |
gpt-image-2-vip | 需要更高优先级或更高规格尺寸时使用。 | 与 gpt-image-2-pro 相同，size 传 1K 到 4K 像素值。 |
同步图片生成
bash
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
}'生成字段
| 字段 | 说明 |
|---|---|
model | 必填。模型名，例如 gpt-image-2、gpt-image-2-pro 或 gpt-image-2-vip。 |
prompt | 必填。图片描述，建议写清主体、场景、风格、构图、比例和用途。 |
size | 可选。输出尺寸。gpt-image-2 可传比例或 1K 像素值；gpt-image-2-pro 和 gpt-image-2-vip 传像素值。 |
n | 可选。生成数量，以模型和账户可用范围为准。 |
response_format | 可选。常用 url 或 b64_json，以 API Reference 为准。 |
同步图片编辑
multipart 文件上传是默认调用方式：
bash
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"除 multipart 文件上传外，部分 API Key 分组支持在同步接口中使用 application/json 直接传图片 URL。是否支持 JSON URL、单图或多图，以及图片数量限制，均以当前 API Key 所属分组和所选模型的实际能力为准；不要假设不同分组具备完全相同的输入方式。
同步单图 URL：
bash
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 传为 URL 数组：
json
{
"model": "gpt-image-2",
"prompt": "保留第一张图的主体，参考第二张图的色彩和细节。",
"image": [
"https://example.com/subject.png",
"https://example.com/style.png"
],
"size": "1024x1024",
"n": 1
}JSON URL 输入应使用无需登录、无需额外请求头且可公网直接下载的稳定 HTTPS 图片地址。
编辑字段
| 字段 | 说明 |
|---|---|
image | 必填。默认传 multipart 图片文件；部分 API Key 分组也支持一个 JSON 图片 URL 或 URL 数组，具体以分组和模型能力为准。 |
mask | 可选。局部修改时使用的蒙版文件，具体支持以 API Reference 为准。 |
model | 必填。推荐使用 gpt-image-2-pro 或 gpt-image-2-vip 处理高质量编辑。 |
prompt | 必填。写清要保留的内容、要修改的区域和目标效果。 |
size | 可选。输出尺寸，gpt-image-2-pro 与 gpt-image-2-vip 支持同一组像素值。 |
尺寸和比例
gpt-image-2 支持直接传比例，例如 16:9，也可以传 1K 像素值。常用取值如下：
| 比例 | size 示例 |
|---|---|
auto | auto |
1:1 | 1024x1024 |
16:9 | 16:9 或 1672x941 |
9:16 | 9:16 或 941x1672 |
4:3 | 4:3 或 1443x1090 |
3:4 | 3:4 或 1090x1443 |
3:2 | 3:2 或 1536x1024 |
2:3 | 2:3 或 1024x1536 |
5:4 | 5:4 或 1408x1120 |
4:5 | 4:5 或 1120x1408 |
21:9 | 21:9 或 1920x832 |
9:21 | 9:21 或 832x1920 |
2:1 | 2:1 或 1792x896 |
1:2 | 1:2 或 896x1792 |
gpt-image-2-pro 和 gpt-image-2-vip 的尺寸调用方式相同，size 传像素值，不传比例。支持 1K、2K、4K 常用尺寸，也支持满足约束的自定义像素值。
| 比例 | 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 |
自定义像素值需要同时满足：
- 最大边长不超过
3840px。 - 宽和高都必须是
16的倍数。 - 长边与短边比例不超过
3:1。 - 总像素数不少于
655360，且不超过8294400。
同步返回结果
json
{
"created": 1711234567,
"data": [
{
"url": "https://example.com/images/generated-image.png",
"revised_prompt": "A clean product photo on a white background."
}
]
}处理建议：
- 优先读取
data数组，不要只判断某个 URL 字段是否存在。 - 当
response_format为url时，保存data[].url、模型名、prompt、尺寸和业务订单号。 - 当
response_format为b64_json时，先将data[].b64_json写入自己的对象存储，再在业务库保存可访问地址。 - 如果接口返回 HTTP 错误，记录错误响应、请求参数和业务请求 ID，修正 prompt、图片格式或尺寸后再重试。
Prompt 建议
- 商品图：写清商品主体、背景、光线、镜头角度、是否保留包装文字。
- 海报图：写清用途、主视觉、版式、留白位置和文字区域，不要把大量文案塞进 prompt。
- 参考图编辑：明确哪些内容必须保留，哪些内容需要替换，避免只写“优化一下”。
- 固定比例输出：同时写入画面比例和
size，例如 prompt 写“竖版 9:16 海报”，size传720x1280。