跳转到主要内容
使用 POST https://api.apione.ai/v1/images/edits 编辑图像。

运行示例前准备

安装 Python 3，并在运行脚本的同一个 Python 环境安装依赖：
如果你的系统使用 python3，安装和运行时都使用 python3。Windows 也可以对应使用 py -m pip install requests 与 py example.py。使用虚拟环境时，先激活环境。 在 API 密钥页创建密钥，从当前 Key 可用的模型列表复制支持图像编辑的模型 ID，然后在运行脚本的终端设置变量。下面的大写值是占位符，需要替换。
变量只对当前终端及其启动的子进程生效。在同一终端运行后面的示例；IDE、容器或新终端需要另行配置。不要把真实密钥提交到代码仓库。

请求前确认

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

请求结构

请求至少需要模型、编辑提示词和图片输入。不同模型可能使用图片 URL、Base64、文件标识或其他字段，因此先以参数查询结果为准。
将请求发送到：
如果模型要求 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，请按参数说明调整请求。

结果质量检查

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

常见错误

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

参数返回为空时

接口返回 HTTP 200，但 params 为 []、request 为 {} 或 billingMode 为空时，仅表示该响应没有声明相应信息，不代表模型不支持、参数可以任意填写或调用免费。chargeModes 中的 usage、request、second、image 是响应列出的模式名称，不等于该模型同时按四种方式收费。
  1. 在 APIONE 模型详情和当前 Key 分组中核对可用协议与价格。
  2. 有明确模型参数说明时，以该说明确定尺寸、质量、参考图、蒙版等字段；不要照搬其他模型的枚举。
  3. 没有明确参数依据时，先验证本页的最小请求，暂不提交可选字段或批量任务。
  4. 携带模型 ID、接口、请求时间和实际请求标识联系支持确认参数，不发送完整 Key。
下一步：图像生成、媒体参数与计费、错误码与排查。