> ## Documentation Index
> Fetch the complete documentation index at: https://docs.geeknow.top/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAI Images 兼容图像编辑

> 使用 `POST /v1/images/edits` 或 `POST /v1/edits` 基于已有图片执行编辑、局部重绘和图生图。

# OpenAI Images 兼容图像编辑

图像编辑使用与生成相同的模型家族，但入口换成编辑路由。

* 兼容 `POST /v1/images/edits` 和 `POST /v1/edits` 两个入口。
* 同时支持 `multipart/form-data` 和 JSON 请求体。
* 传 `image` 为图生图，额外传 `mask` 为局部重绘。
* `gpt-image-1` 在编辑场景下默认 `quality = standard`，`n` 不传或传 `0` 时回退为 `1`。

## 方法与路径

| Method | Path               |
| ------ | ------------------ |
| `POST` | `/v1/images/edits` |
| `POST` | `/v1/edits`        |

## 请求示例

<CodeGroup>
  ```bash theme={null}
  curl -X POST https://www.geeknow.top/v1/images/edits \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -F "model=gpt-image-1" \
    -F "prompt=把背景改成科技感办公室，保留主体构图" \
    -F "image=@input.png" \
    -F "size=1024x1024" \
    -F "watermark=false"
  ```

  ```python theme={null}
  import requests

  with open("input.png", "rb") as f:
      resp = requests.post(
          "https://www.geeknow.top/v1/images/edits",
          headers={"Authorization": "Bearer YOUR_API_KEY"},
          data={
              "model": "gpt-image-1",
              "prompt": "把背景改成科技感办公室，保留主体构图",
              "size": "1024x1024",
              "watermark": "false",
          },
          files={"image": ("input.png", f, "image/png")},
          timeout=60,
      )

  print(resp.json())
  ```

  ```javascript theme={null}
  const formData = new FormData();
  formData.append("model", "gpt-image-1");
  formData.append("prompt", "把背景改成科技感办公室，保留主体构图");
  formData.append("size", "1024x1024");
  formData.append("watermark", "false");
  formData.append("image", fileInput.files[0]);

  const response = await fetch("https://www.geeknow.top/v1/images/edits", {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
    },
    body: formData,
  });

  console.log(await response.json());
  ```
</CodeGroup>

## 响应示例

<ResponseExample>
  ```json 200 theme={null}
  {
    "created": 1735689600,
    "data": [
      {
        "url": "https://.../images/edit-abc123.png",
        "revised_prompt": "把背景改成科技感办公室，保留主体构图"
      }
    ]
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "message": "failed to parse image edit form request",
      "type": "invalid_request_error",
      "param": "",
      "code": "invalid_request"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "message": "Invalid API key provided",
      "type": "invalid_request_error",
      "param": "",
      "code": "invalid_api_key"
    }
  }
  ```

  ```json 402 theme={null}
  {
    "error": {
      "message": "用户额度不足",
      "type": "new_api_error",
      "param": "",
      "code": "insufficient_user_quota"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "message": "当前请求频率过高，请稍后再试",
      "type": "new_api_error",
      "param": "",
      "code": "too_many_requests"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "message": "bad response body",
      "type": "new_api_error",
      "param": "",
      "code": "bad_response_body"
    }
  }
  ```
</ResponseExample>

## 认证

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Body

<ParamField body="image" type="file | string | object" required>
  编辑输入图。`multipart/form-data` 下通常是文件；JSON 场景下可以是 URL、Base64 或对象结构。
</ParamField>

<ParamField body="prompt" type="string" required>
  编辑说明。用于描述要保留什么、修改什么。
</ParamField>

<ParamField body="model" type="string">
  模型名称。未传时最终是否有默认行为取决于上游，不建议省略。
</ParamField>

<ParamField body="mask" type="file | string | object">
  局部重绘遮罩。透明区域通常表示允许编辑的区域。
</ParamField>

<ParamField body="n" type="integer">
  输出数量。不传或显式传 `0` 时按 `1` 处理。
</ParamField>

<ParamField body="size" type="string">
  输出尺寸。具体可用值与目标模型有关。
</ParamField>

<ParamField body="quality" type="string">
  质量字段。`gpt-image-1` 在编辑表单场景下默认补成 `standard`。
</ParamField>

<ParamField body="watermark" type="boolean">
  显式水印开关。显式传 `false` 表示明确关闭，不传表示沿用默认策略。
</ParamField>

## Response

<ResponseField name="created" type="integer">
  编辑结果生成时间戳。
</ResponseField>

<ResponseField name="data[].url" type="string">
  结果图片 URL。
</ResponseField>

<ResponseField name="data[].b64_json" type="string">
  当请求 Base64 格式时返回的图片数据。
</ResponseField>

<ResponseField name="data[].revised_prompt" type="string">
  上游可能改写后的编辑提示词。
</ResponseField>

## 使用场景

### 基础图生图

```bash theme={null}
curl -X POST https://www.geeknow.top/v1/images/edits \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-1" \
  -F "prompt=把人物服装改成深蓝色西装" \
  -F "image=@portrait.png"
```

### 局部重绘

```bash theme={null}
curl -X POST https://www.geeknow.top/v1/images/edits \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-1" \
  -F "prompt=把背景改成现代办公室" \
  -F "image=@input.png" \
  -F "mask=@mask.png"
```

### 使用旧版别名

```bash theme={null}
curl -X POST https://www.geeknow.top/v1/edits \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-1" \
  -F "prompt=保留主体，增强灯光层次" \
  -F "image=@input.png"
```

## 注意事项

<Warning>
  编辑接口虽然同时兼容 JSON 和表单，但不同上游对字段形状的要求差异很大。最稳的做法仍然是使用 `multipart/form-data` 提交 `image`、`prompt`、`mask` 这类编辑字段。
</Warning>

## 相关接口

* [OpenAI Images 兼容概览](./overview)
* [OpenAI Images 兼容图像生成](./generation)
* [上传图片](/api-reference/uploads/image-upload)