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

# 图片编辑 API 参考

> gpt-image-2-vip 图片编辑 API 参考与在线调试 — 上传参考图 + 指令进行单图改图或多图融合，可用 size 锁定输出尺寸

<Info>
  右侧的交互式 Playground 支持直接上传本地图片。请在 **Authorization** 中填入你的 API Key（格式：`Bearer sk-xxx`），选择图片与填入 `prompt`、`model`、`size` 后一键发送即可。
</Info>

<Tip>
  **场景说明**：本页用于「基于一张或多张参考图改图 / 融合生成」。请求为 `multipart/form-data` 格式。如需纯文本生成图片，请使用 [文生图接口](/api-capabilities/gpt-image-2-vip/text-to-image)。

  **与 `gpt-image-2-all` 的区别**：调用结构完全一致，只多一个 `size` 字段；不需要锁尺寸、追求出图速度时改用 [`gpt-image-2-all`](/api-capabilities/gpt-image-2-all/image-edit)。
</Tip>

<Warning>
  **🖥️ 浏览器 Playground 限制**

  本端点**默认返回 base64 字符串（`b64_json`）**，体积可达数 MB，浏览器 Playground **可能弹出** `请求时发生错误: unable to complete request` ——**实际请求已经成功**，只是浏览器无法显示这么长的 base64。

  **推荐做法**：想要 base64 或要传超大参考图时，**复制下方"代码示例"到本地运行**，代码会自动处理上传与解码。
</Warning>

<Warning>
  **📎 多图融合顺序有意义**

  `image` 字段可重复传入多张参考图，**顺序将作为 prompt 中「图1/图2/图3」的引用依据**。建议在 prompt 中显式指代，例如：

  > 把图1的人物放进图2的场景，参考图3的画风

  推荐单张 **≤ 10MB**，格式 `png` / `jpg` / `webp`，过大的图可能触发网关限制。
</Warning>

<Tip>
  **🎯 保形改图小技巧**：传 `size=auto`（或不传 `size`）时，输出会**跟随 prompt 里点名要修改的那张图的尺寸比例**——多图场景下**不一定是第一张**。

  例如 prompt 写"**修改图2**，把图2 的衣服和帽子改成图1 里的样子"，那图2 是 1:1，则输出也是 1:1（即便图1 是横版 16:9）。

  对换装、加帽子、修图等保形场景特别好用。如果 prompt 没明确指代要改哪张，模型会自行判断；需要切换到 30 档锁定尺寸时再显式传 `size`。
</Tip>

<Warning>
  **⚠️ 关键参数说明**

  * **`size`**：**改图建议传 `auto`（或不传）**——模型会**根据 prompt 里点名要修改的那张图的尺寸比例**输出，多图场景下不一定是第一张。例如 prompt 写"修改图2，把图2 的衣服换成图1 的样子"，输出比例就跟图2 一致；prompt 没明确指代时由模型自行判断。需要强制改变尺寸时，从 30 档常见尺寸里选；写法用半角小写 `x`，如 `2048x1360`、`3840x2160`。完整表见 [概览页](/api-capabilities/gpt-image-2-vip/overview#支持的-size30-档完整对照表)。
  * **`quality`**：❌ 不接受，**不要传**。
  * **`n`**：❌ 不接受，单次仅返回 1 张图。
  * **`response_format`**：不传默认返回 base64（纯 base64 无前缀，2026-07 实测）；传 `"url"` 可返回图片 URL。**强依赖 URL 输出**的业务建议把令牌分组切到 `image2_OSS`，稳定输出 URL、不降级为 base64。
</Warning>

## 代码示例

### Python

**单图编辑**：

```python theme={null}
import requests

API_KEY = "sk-your-api-key"

with open("photo.png", "rb") as f:
    response = requests.post(
        "https://api.apiyi.com/v1/images/edits",
        headers={"Authorization": f"Bearer {API_KEY}"},
        data={
            "model": "gpt-image-2-vip",
            "prompt": "把背景换成海边黄昏",
            "size": "2048x1360"          # 3:2 2K Recommended
        },
        files=[
            ("image", ("photo.png", f, "image/png"))
        ],
        timeout=300  # 保守值，吸收长尾 + 图片上传/下载耗时
    ).json()

print(response["data"][0]["url"])
```

**多图融合**：

```python theme={null}
import requests

with open("ref1.png", "rb") as f1, \
     open("ref2.png", "rb") as f2, \
     open("ref3.png", "rb") as f3:
    response = requests.post(
        "https://api.apiyi.com/v1/images/edits",
        headers={"Authorization": "Bearer sk-your-api-key"},
        data={
            "model": "gpt-image-2-vip",
            "prompt": "把图1的人物放进图2的场景，参考图3的画风",
            "size": "2048x2048"          # 1:1 2K Recommended
        },
        files=[
            ("image", ("ref1.png", f1, "image/png")),
            ("image", ("ref2.png", f2, "image/png")),
            ("image", ("ref3.png", f3, "image/png"))
        ],
        timeout=300  # 保守值，吸收长尾 + 图片上传/下载耗时
    ).json()

# 实测（2026-07）b64_json 为纯 base64（无 data: 前缀）；历史版本曾含前缀，做个检测最稳
import base64
b64 = response["data"][0]["b64_json"]
if b64.startswith("data:"):
    b64 = b64.split(",", 1)[1]
with open("edited.png", "wb") as f:
    f.write(base64.b64decode(b64))
```

### cURL

**单图编辑**：

```bash theme={null}
curl -X POST "https://api.apiyi.com/v1/images/edits" \
  -H "Authorization: Bearer sk-your-api-key" \
  -F "model=gpt-image-2-vip" \
  -F "prompt=把背景换成海边黄昏" \
  -F "size=2048x1360" \
  -F "image=@./photo.png"
```

**多图融合**：

```bash theme={null}
curl -X POST "https://api.apiyi.com/v1/images/edits" \
  -H "Authorization: Bearer sk-your-api-key" \
  -F "model=gpt-image-2-vip" \
  -F "prompt=把图1的人物放进图2的场景，参考图3的画风" \
  -F "size=2048x2048" \
  -F "image=@./ref1.png" \
  -F "image=@./ref2.png" \
  -F "image=@./ref3.png"
```

### Node.js（原生 fetch + FormData）

```javascript theme={null}
import fs from 'node:fs';

const form = new FormData();
form.append('model', 'gpt-image-2-vip');
form.append('prompt', '把背景换成太空');
form.append('size', '2048x1360');
form.append(
  'image',
  new Blob([fs.readFileSync('./photo.png')]),
  'photo.png'
);

const resp = await fetch('https://api.apiyi.com/v1/images/edits', {
    method: 'POST',
    headers: { 'Authorization': 'Bearer sk-your-api-key' },
    body: form
});
const data = await resp.json();
console.log(data.data[0].url);
```

### 浏览器 JavaScript（File 对象）

```javascript theme={null}
// <input type="file" id="fileInput" multiple>
const files = document.getElementById('fileInput').files;
const form = new FormData();
form.append('model', 'gpt-image-2-vip');
form.append('prompt', '把这几张图融合成一张海报');
form.append('size', '2048x2048');
for (const f of files) form.append('image', f);

const resp = await fetch('https://api.apiyi.com/v1/images/edits', {
    method: 'POST',
    headers: { 'Authorization': 'Bearer sk-your-api-key' },
    body: form
});
const { data } = await resp.json();
document.getElementById('result').src = data[0].url;
```

## 参数说明速查

| 字段       | 类型   | 必填 | 说明                                                                                |
| -------- | ---- | -- | --------------------------------------------------------------------------------- |
| `model`  | text | 是  | 固定填 `gpt-image-2-vip`                                                             |
| `prompt` | text | 是  | 改图/融合的自然语言描述                                                                      |
| `image`  | file | 是  | 参考图，可重复多次（数组字段）                                                                   |
| `size`   | text | 否  | 输出尺寸：`auto`（默认，**跟随 prompt 里点名要修改的那张图的比例**，多图下不一定是第一张）或 30 档之一；写法 `宽x高`（半角小写 `x`） |

<Tip>
  **多轮迭代**：把上一次的输出图片作为下一次的 `image` 输入，配合新的编辑指令，可逐步精调画面效果。每一轮都可以独立指定 `size`。
</Tip>

## 响应格式

与文生图接口一致：**默认返回 base64**（`data[0].b64_json`，纯 base64 无前缀，2026-07 实测）。如需 **图片 URL**：显式传 `response_format: "url"` 即可；**强依赖 URL 输出**的业务建议把令牌分组切到 **`image2_OSS`**，稳定输出 URL、不降级为 base64。`data[0]` 中只会出现 `url` 或 `b64_json` 之一，不会两者都返回。

**`b64_json` 模式**（默认）：

```json theme={null}
{
  "data": [
    {
      "b64_json": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ],
  "created": 1778037127,
  "usage": {
    "input_tokens": 98,
    "output_tokens": 1185,
    "total_tokens": 1283
  }
}
```

**`url` 模式**（显式传 `response_format: "url"`；强依赖 URL 建议用 `image2_OSS` 分组）：

```json theme={null}
{
  "data": [
    {
      "url": "https://r2cdn.copilotbase.com/r2cdn2/0e82148a-bec0-4b42-bbca-117c6b42581b.png"
    }
  ],
  "created": 1778037331,
  "usage": {
    "input_tokens": 30,
    "output_tokens": 2074,
    "total_tokens": 2104
  }
}
```

<Warning>
  2026-07 实测 `b64_json` 字段为**纯 base64（不含 `data:` 前缀）**，需解码或自行拼接前缀后使用；**历史版本曾直接带前缀**。请先做 `startsWith('data:')` 检测再处理，兼容两种形态。
</Warning>

## 相关资源

<CardGroup cols={2}>
  <Card title="模型概览（含完整 size 表）" icon="sparkles" href="/api-capabilities/gpt-image-2-vip/overview">
    30 档 size 完整对照表、定价、技术规格
  </Card>

  <Card title="文生图 API" icon="wand-sparkles" href="/api-capabilities/gpt-image-2-vip/text-to-image">
    `/v1/images/generations` 兼容端点
  </Card>

  <Card title="姐妹模型 gpt-image-2-all" icon="copy" href="/api-capabilities/gpt-image-2-all/image-edit">
    不需要锁尺寸时调用方式一致，出图更快
  </Card>
</CardGroup>


## OpenAPI

````yaml api-reference/gpt-image-2-vip-edit-openapi.yaml POST /v1/images/edits
openapi: 3.1.0
info:
  title: gpt-image-2-vip 图片编辑 API
  description: >
    GPT 图像生成 Codex 官逆模型 `gpt-image-2-vip` — 图片编辑接口。


    - 支持单图改图与多图融合（同名 `image` 字段可重复传，多图按上传顺序排序）

    - 请求格式为 `multipart/form-data`

    - 在 prompt 中可用「图1/图2/图3」指代上传顺序

    - 支持 30 档常见 size（10 比例 × 1K / 2K / 4K，所有档位统一价 $0.03/张）

    - **默认返回 base64 (`b64_json`)，可切换为 R2 CDN 链接 (`url`)**；响应中 `data[0]` 只会出现
    `url` **或** `b64_json` 之一，不会两者都返回


    **认证方式**：在请求头中添加 `Authorization: Bearer YOUR_API_KEY`


    **获取 API Key**：访问 [API易控制台](https://api.apiyi.com/token) 创建令牌
  version: 1.0.0
servers:
  - url: https://api.apiyi.com
    description: 主要端点
  - url: https://vip.apiyi.com
    description: 备用端点
security:
  - bearerAuth: []
paths:
  /v1/images/edits:
    post:
      tags:
        - 图片编辑
      summary: 图片编辑：根据指令编辑或融合参考图，可锁定输出尺寸
      description: >
        使用 `gpt-image-2-vip` 模型，根据文本指令对输入图片进行编辑或多图融合，并通过 `size` 字段锁定输出尺寸。


        - 必须提供至少一张输入图片（`image` 字段）

        - 多张参考图：**重复传同名 `image` 字段**，例如 `-F image=@a.png -F
        image=@b.png`（按上传顺序对应 prompt 中的「图1/图2/...」）

        - 单张图片推荐 ≤ 10MB，格式 png/jpg/webp

        - 强烈建议传 `size`（30 档之一），不要传 `quality` / `n`

        - 如需纯文本生成图片，请使用 [文生图接口](/api-capabilities/gpt-image-2-vip/text-to-image)
      operationId: editGptImage2VipImage
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/EditImageRequest'
            encoding:
              image:
                contentType: image/png, image/jpeg, image/webp
      responses:
        '200':
          description: 成功生成图片。响应默认返回 base64（`data[0].b64_json`），不会同时返回 `url`。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageResponse'
              example:
                data:
                  - b64_json: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...
                created: 1778037127
                usage:
                  input_tokens: 98
                  output_tokens: 1185
                  total_tokens: 1283
        '400':
          description: size 取值不在 30 档内或格式错误
        '401':
          description: 未授权 - API Key 无效
        '429':
          description: 请求频率超限或额度不足
        '500':
          description: 服务器内部错误
      security:
        - bearerAuth: []
components:
  schemas:
    EditImageRequest:
      type: object
      required:
        - model
        - prompt
        - image
      properties:
        model:
          type: string
          description: 模型名称，固定为 gpt-image-2-vip
          enum:
            - gpt-image-2-vip
          default: gpt-image-2-vip
        prompt:
          type: string
          description: 编辑/融合指令。多图场景可用「图1/图2/图3」指代 image 字段的上传顺序
          example: 把图1的人物放进图2的场景，参考图3的画风
        image:
          type: array
          description: >-
            参考图。**单图直接传一次，多图重复传同名 `image` 字段**（例如 `-F image=@a.png -F
            image=@b.png`），按上传顺序对应 prompt 中的「图1/图2/...」。推荐单张 ≤ 10MB，格式
            png/jpg/webp。
          items:
            type: string
            format: binary
        size:
          type: string
          description: >
            输出尺寸。**改图场景推荐传 `auto`（或不传）**——模型会**根据 prompt
            里点名要修改的那张图的尺寸比例**输出（多图场景下不一定是第一张）。例如 prompt 写"修改图2，把图2 的衣服换成图1
            的样子"，则输出比例跟图2 一致。如果 prompt 没明确指代，模型会自行判断。如需强制改变尺寸，从 30
            档常见尺寸里选；写法：`宽x高`（半角小写 x），如 `2048x1360`、`3840x2160`。所有档位统一价 $0.03/张。
          enum:
            - auto
            - 1280x1280
            - 848x1280
            - 1280x848
            - 960x1280
            - 1280x960
            - 1024x1280
            - 1280x1024
            - 720x1280
            - 1280x720
            - 1280x544
            - 2048x2048
            - 1360x2048
            - 2048x1360
            - 1536x2048
            - 2048x1536
            - 1632x2048
            - 2048x1632
            - 1152x2048
            - 2048x1152
            - 2048x864
            - 2880x2880
            - 2336x3520
            - 3520x2336
            - 2480x3312
            - 3312x2480
            - 2560x3216
            - 3216x2560
            - 2160x3840
            - 3840x2160
            - 3840x1632
          example: 2048x1360
    ImageResponse:
      type: object
      description: >
        图片编辑响应。**默认返回 base64**（`data[0].b64_json`）；如需 `url`，请改用 `image2_OSS`
        分组并传 `response_format=url`。`data[0]` 中**只会出现 `url` 或 `b64_json`
        之一**，不会两者都返回。
      properties:
        data:
          type: array
          description: 生成结果数组（本模型单次返回 1 张）
          items:
            type: object
            properties:
              url:
                type: string
                description: R2 CDN 加速链接（使用 image2_OSS 分组并传 response_format=url 时返回）
              b64_json:
                type: string
                description: Base64 编码的 data URL（默认返回，已含 data:image/png;base64, 前缀）
        created:
          type: integer
          description: 创建时间戳（Unix 秒）
        usage:
          type: object
          description: Token 用量统计
          properties:
            input_tokens:
              type: integer
              description: 输入 token 数
            output_tokens:
              type: integer
              description: 输出 token 数（含图片像素折算）
            total_tokens:
              type: integer
              description: 总 token 数
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 在 API易控制台获取的 API Key

````