MoonApiX Docs

Appearance

GPT Image ​

GPT Image 系列用于通用图片生成和图片编辑，适合产品图、营销海报、社媒素材、参考图改写、背景替换和画面细节重绘。MoonApiX 价格页当前常见模型包括 gpt-image-2、gpt-image-2-pro 和 gpt-image-2-vip。请求时请以 MoonApiX 后台、价格页或 GET /v1/models 返回的模型名为准。

MoonApiX 的 GPT Image 使用 OpenAI Images 兼容入口。文生图调用 /v1/images/generations，基于图片修改调用 /v1/images/edits。同步成功时读取响应里的 data 数组；如果返回 URL，使用 data[].url；如果返回图片内容，使用 data[].b64_json 并落到自己的文件存储。长耗时任务也可以使用 /v1/images/generations/async 或 /v1/images/edits/async，先拿任务 ID，再查询结果 URL。

gpt-image-* 不推荐通过 /v1/chat/completions 生成图片。请使用本页的 Images API 入口提交图片生成或编辑请求；聊天补全接口主要用于对话文本和视觉理解类模型，不作为 GPT Image 的稳定图片生成入口。

推荐入口 ​

能力路径说明
图片生成/v1/images/generations从文本 prompt 生成图片。
图片异步生成/v1/images/generations/async先返回任务 ID，适合长耗时图片生成。
图片编辑/v1/images/edits上传图片并按 prompt 修改画面，适合参考图改写、换背景和局部修改。
图片异步编辑/v1/images/edits/async使用 JSON 图片 URL 或 Base64 图片内容提交编辑任务。
图片变体/v1/images/variations模型支持时基于原图生成相近版本。

不要把 gpt-image-2 放到 /v1/chat/completions 中当作图片生成模型调用。客户端或 SDK 只支持 Chat Completions 时，请在图片功能处单独配置 Images API 请求。

模型选择 ​

模型建议用途尺寸调用
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://moonapix.com/v1/images/generations \
  -H "Authorization: Bearer <MOONAPIX_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 为准。

图片编辑 ​

bash
curl https://moonapix.com/v1/images/edits \
  -H "Authorization: Bearer <MOONAPIX_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"

异步任务 ​

同步接口会等待图片生成或编辑完成。如果客户端不适合保持长连接，请使用图片异步接口：

bash
curl https://moonapix.com/v1/images/generations/async \
  -H "Authorization: Bearer <MOONAPIX_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
  }'

提交成功后保存响应里的 id，再查询：

bash
curl https://moonapix.com/v1/images/tasks/task_xxx \
  -H "Authorization: Bearer <MOONAPIX_API_KEY>"

任务成功时读取 data[].url。异步结果始终返回 URL；如果生成过程得到的是图片内容，MoonApiX 会转换成可访问图片 URL 后再写入任务结果。

编辑字段 ​

字段说明
image必填。输入图片文件，可作为参考图或待修改图片。
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 示例
autoauto
1:11024x1024
16:916:9 或 1672x941
9:169:16 或 941x1672
4:34:3 或 1443x1090
3:43:4 或 1090x1443
3:23:2 或 1536x1024
2:32:3 或 1024x1536
5:45:4 或 1408x1120
4:54:5 或 1120x1408
21:921:9 或 1920x832
9:219:21 或 832x1920
2:12:1 或 1792x896
1:21:2 或 896x1792

gpt-image-2-pro 和 gpt-image-2-vip 的尺寸调用方式相同，size 传像素值，不传比例。支持 1K、2K、4K 常用尺寸，也支持满足约束的自定义像素值。

比例1K2K4K
autoautoautoauto
1:11024x10242048x20482880x2880
16:91280x7202048x11523840x2160
9:16720x12801152x20482160x3840
4:31152x8642304x17283264x2448
3:4864x11521728x23042448x3264
3:21536x10242048x13603504x2336
2:31024x15361360x20482336x3504
5:41120x8962240x17923200x2560
4:5896x11201792x22402560x3200
21:91456x6242912x12483840x1648
9:21624x14561248x29121648x3840
3:12048x688-3840x1280
1:3688x2048-1280x3840
2:11536x7683072x15363840x1920
1:2768x15361536x30721920x3840

自定义像素值需要同时满足：

  • 最大边长不超过 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。

相关页面 ​