图片编辑

图片编辑接口用于基于上传图片和 prompt 修改画面，适合换背景、局部修改、风格统一和商品图处理。是否支持编辑以所选图片模型说明为准，GPT Image 系列通常优先用于该场景。

接口路径

方法	路径	返回方式
POST	/v1/images/edits	同步返回编辑后的图片结果。
POST	/v1/images/edits/async	先返回任务 ID，随后查询编辑结果。

请求示例

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"

常用字段

字段	说明
image	输入图片文件。
model	图片模型名，例如 gpt-image-2-pro。
prompt	编辑目标描述。
mask	蒙版文件，以 API Reference 为准。
size	输出尺寸。

结果处理

场景	处理方式
商品图编辑	保存原图、编辑 prompt 和结果图。
局部修改	同步保存 mask 文件或 mask 来源信息。
失败重试	复用原始文件和请求参数重新提交。
异步编辑	保存 id，轮询 GET /v1/images/tasks/{task_id}，成功后读取 data[].url。

接入建议

• 输入图片要清晰，主体边缘尽量完整。
• 对局部修改，请在 prompt 中写清保留内容和修改区域。
• 需要上传本地图片文件时使用同步 /v1/images/edits；输入已经是公网 URL 或 Base64 图片内容时，可以使用 图片异步任务。
• 需要稳定复用图片时，先看 上传与素材。

相关页面

• 创建和编辑图片汇总
• 图片异步任务
• GPT Image
• 图片生成
• 图片变体
• API Reference