---
title: GPT Image 图片编辑
description: 使用本地文件或图片 URL 进行参考图编辑，支持 multipart 与 JSON 请求示例。
api: "POST /v1/images/edits"
---

使用参考图和提示词编辑图片。上传本地文件时使用 multipart；使用公开图片 URL 时发送 JSON 请求。

<RequestExample>
```bash 上传本地图片
curl https://sub.vcnovb.cn/v1/images/edits \
  -H "Authorization: Bearer $VC_API_KEY" \
  -F 'model=gpt-image-2' \
  -F 'prompt=保留杯子的造型和颜色，将背景改为浅灰色摄影棚' \
  -F 'image=@reference.png' \
  -F 'n=1' \
  -F 'size=1024x1024' \
  -F 'response_format=url'
```
```bash JSON · 图片 URL
curl https://sub.vcnovb.cn/v1/images/edits \
  -H "Authorization: Bearer $VC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "保留主体，将背景改为海边日落",
    "images": [{"image_url": "https://example.com/reference.png"}],
    "n": 1, "size": "1024x1024", "response_format": "url"
  }'
```
```python Python · 本地文件
import os
import requests

with open("reference.png", "rb") as image:
    response = requests.post(
        "https://sub.vcnovb.cn/v1/images/edits",
        headers={"Authorization": f"Bearer {os.environ['VC_API_KEY']}"},
        data={"model": "gpt-image-2", "prompt": "保留主体，将背景改为海边日落",
              "n": "1", "size": "1024x1024", "response_format": "url"},
        files={"image": ("reference.png", image, "image/png")},
        timeout=180,
    )
response.raise_for_status()
print(response.json())
```
```javascript JavaScript · 图片 URL
const response = await fetch("https://sub.vcnovb.cn/v1/images/edits", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VC_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "gpt-image-2", prompt: "保留主体，将背景改为海边日落",
    images: [{ image_url: "https://example.com/reference.png" }],
    n: 1, size: "1024x1024", response_format: "url",
  }),
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());
```
</RequestExample>

<ResponseExample>
```json 编辑成功
{"created":1794614400,"data":[{"url":"https://example.com/edited.png"}]}
```
```json Base64
{"created":1794614400,"data":[{"b64_json":"BASE64_IMAGE_DATA"}]}
```
</ResponseExample>

## 请求参数

<ParamField body="model" type="string" required>具备图片编辑能力的模型，例如已开放的 gpt-image-2。</ParamField>
<ParamField body="prompt" type="string" required>编辑提示词，说明需要保留的内容和需要修改的部分。</ParamField>
<ParamField body="image" type="file">multipart 的本地图片文件。与 JSON 的 images 二选一。</ParamField>
<ParamField body="images" type="array<object>">JSON 请求使用 `[{"image_url":"https://..."}]`。图片必须可由服务端访问；多图数量和用途受模型限制。</ParamField>
<ParamField body="mask" type="file | object">编辑遮罩，适用于支持局部编辑的模型。遮罩尺寸和透明区域要求见对应模型说明。</ParamField>
<ParamField body="n" type="integer" default="1">生成数量，使用正整数，建议先用 1。</ParamField>
<ParamField body="size" type="string">目标输出尺寸，不要求与参考图像素尺寸完全相同，但需符合模型支持范围。</ParamField>
<ParamField body="response_format" type="string">`url` 或 `b64_json`。</ParamField>
<ParamField body="input_fidelity" type="string">输入图片保真度，适用于支持该参数的模型；省略时使用模型默认值。</ParamField>

## 常见错误

- multipart 请求不要手动设置 `Content-Type: application/json`，交给客户端生成文件边界。
- `reference.png` 必须真实存在；URL 示例必须替换，不能把本地磁盘路径作为公网 URL。
- 上传失败时检查文件格式、大小和图片 URL 的可访问性。
- 编辑结果从 `data[].url` 或 `data[].b64_json` 读取，分别对应下载地址和 Base64 图片数据。

Grok 图片模型的 JSON 图片字段有所不同，见[Grok Image](/models/image/grok)。