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

# 图像编辑

> 使用参考图和编辑提示词调用图像编辑端点。

使用 `POST https://api.apione.ai/v1/images/edits` 编辑图像。

## 运行示例前准备

安装 Python 3，并在运行脚本的同一个 Python 环境安装依赖：

```bash theme={null}
python -m pip install requests
```

如果你的系统使用 `python3`，安装和运行时都使用 `python3`。Windows 也可以对应使用 `py -m pip install requests` 与 `py example.py`。使用虚拟环境时，先激活环境。

在 [API 密钥页](https://apione.ai/zh/app/api-keys)创建密钥，从[当前 Key 可用的模型列表](https://apione.ai/docs/models/catalog.md)复制支持图像编辑的模型 ID，然后在运行脚本的终端设置变量。下面的大写值是占位符，需要替换。

> [tab] macOS / Linux
>
> ```bash theme={null}
> export APIONE_API_KEY="YOUR_APIONE_API_KEY"
> export APIONE_IMAGE_EDIT_MODEL="YOUR_IMAGE_EDIT_MODEL"
> ```

> [tab] Windows PowerShell
>
> ```powershell theme={null}
> $env:APIONE_API_KEY = "YOUR_APIONE_API_KEY"
> $env:APIONE_IMAGE_EDIT_MODEL = "YOUR_IMAGE_EDIT_MODEL"
> ```

变量只对当前终端及其启动的子进程生效。在同一终端运行后面的示例；IDE、容器或新终端需要另行配置。不要把真实密钥提交到代码仓库。

## 请求前确认

1. 当前 Key 可以调用目标图像编辑模型。
2. `/v1/models/{model}/params` 显示该模型支持编辑或参考图输入。
3. 图片类型、大小、数量和传递方式符合该模型要求。

## 请求结构

请求至少需要模型、编辑提示词和图片输入。不同模型可能使用图片 URL、Base64、文件标识或其他字段，因此先以参数查询结果为准。

```json theme={null}
{
  "model": "YOUR_IMAGE_EDIT_MODEL",
  "prompt": "保留主体构图，将背景改为傍晚海边",
  "image": "MODEL_SUPPORTED_IMAGE_INPUT"
}
```

将请求发送到：

```text theme={null}
POST https://api.apione.ai/v1/images/edits
Authorization: Bearer YOUR_APIONE_API_KEY
Content-Type: application/json
```

> [!NOTE]
>
> 如果模型要求 multipart、专用参考图字段或额外蒙版，请严格使用该模型参数页的字段。不要把上面示意结构当成所有模型的固定格式。

## 验证结果

* 主体和编辑区域是否符合提示词
* 图片尺寸、格式和透明通道是否满足业务要求
* 控制台中的请求状态、用量和费用
* 响应中的请求 ID 是否可在明细中检索

## 编辑任务拆解

先确定属于哪一类编辑，再选择支持该能力的模型：

| 任务 | 需要确认 |
| - | - |
| 整图重绘 | 参考图输入、提示词、强度或相似度参数 |
| 局部修改 | 是否支持蒙版、蒙版格式和坐标规则 |
| 背景替换 | 透明通道、主体保持能力、输出格式 |
| 多图融合 | 参考图数量、顺序、大小与权重 |
| 风格迁移 | 风格字段是否存在，或仅通过提示词控制 |

## 请求准备流程

1. 通过 `/v1/models` 找到可用的图像编辑模型。
2. 查询 `/v1/models/{model}/params`，确认图片输入方式。
3. 在本地检查文件格式、像素尺寸和文件大小。
4. 先用一张小图和简单提示词验证。
5. 打印完整响应和请求 ID，再实现结果下载。

如果参数页要求 JSON URL 或 Base64，可按模型声明构造 JSON；如果要求 `multipart/form-data`，使用文件上传字段，不要强行发送 JSON。

## Python 请求模板

以下模板仅用于目标模型明确支持 JSON `image` 字段的情况。把 `APIONE_IMAGE_INPUT` 设置为该字段接受的图片 URL、Base64 或文件标识。若使用 URL，需要服务端能读取；本机路径（如 `C:\images\input.png`）不能直接作为远程图片 URL。若模型使用其他字段或 multipart，请按参数说明调整请求。

```bash macOS / Linux theme={null}
export APIONE_IMAGE_INPUT="MODEL_SUPPORTED_IMAGE_INPUT"
```

```powershell Windows PowerShell theme={null}
$env:APIONE_IMAGE_INPUT = "MODEL_SUPPORTED_IMAGE_INPUT"
```

```python theme={null}
import os
import requests

payload = {
    "model": os.environ["APIONE_IMAGE_EDIT_MODEL"],
    "prompt": "保留主体构图，将背景改为傍晚海边",
    "image": os.environ["APIONE_IMAGE_INPUT"],
}

response = requests.post(
    "https://api.apione.ai/v1/images/edits",
    headers={"Authorization": f"Bearer {os.environ['APIONE_API_KEY']}"},
    json=payload,
    timeout=180,
)
print(response.status_code, {name: response.headers[name] for name in ("X-Request-ID", "X-Maxx-Trace-Id", "X-Maxx-Request-ID") if name in response.headers})
print(response.text)
response.raise_for_status()
```

## 结果质量检查

* 主体身份、文字、Logo 或产品结构是否被意外改变；
* 蒙版边缘是否存在明显接缝；
* 输出尺寸和透明通道是否保留；
* 参考图是否包含无权上传的个人或商业素材；
* 重试是否生成了多个结果并产生重复费用。

## 常见错误

| 现象 | 优先检查 |
| - | - |
| 400 参数错误 | 字段名、输入类型、Base64 前缀、URL 可访问性 |
| 413 请求过大 | 图片大小、数量和编码后的体积 |
| 415 或格式错误 | `Content-Type` 与模型要求是否一致 |
| 编辑效果接近重新生成 | 模型是否支持编辑，提示词是否明确保留项 |
| 返回成功但结果无法下载 | URL 有效期、网络和文件存储权限 |

图像包含敏感数据时，不要在日志中保存原图、完整 Base64 或带鉴权参数的下载 URL。

## 参数返回为空时

接口返回 HTTP 200，但 `params` 为 `[]`、`request` 为 `{}` 或 `billingMode` 为空时，仅表示该响应没有声明相应信息，不代表模型不支持、参数可以任意填写或调用免费。`chargeModes` 中的 `usage`、`request`、`second`、`image` 是响应列出的模式名称，不等于该模型同时按四种方式收费。

1. 在 APIONE 模型详情和当前 Key 分组中核对可用协议与价格。
2. 有明确模型参数说明时，以该说明确定尺寸、质量、参考图、蒙版等字段；不要照搬其他模型的枚举。
3. 没有明确参数依据时，先验证本页的最小请求，暂不提交可选字段或批量任务。
4. 携带模型 ID、接口、请求时间和实际请求标识联系支持确认参数，不发送完整 Key。

下一步：[图像生成](https://apione.ai/docs/api/images-generations.md)、[媒体参数与计费](https://apione.ai/docs/api/media-parameters.md)、[错误码与排查](https://apione.ai/docs/support/errors.md)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.