图片编辑

图片编辑覆盖换背景、局部重绘、商品图优化、风格调整和生成变体。Tapapi 本地路由包含 POST /v1/images/edits，但编辑能力不是所有图片模型都支持，生产接入前必须确认模型、渠道、字段和价格。

/v1/tapapi/images/advanced 不是当前稳定图生图入口。不要通过 advanced 传 image_urls 或 mask 做生产图片编辑。

能力区别

能力	输入 -> 输出	当前建议
文生图	text -> image	稳定主线，使用 `/v1/images/generations`
图生图	text + image -> image	规划能力，不要用 `image_urls` 硬接
多参考图	text + 多图 -> image	规划能力，等待模型白名单和计费说明
图片编辑	image + prompt -> image	条件可用，仅模型明确支持时使用
局部重绘	image + mask + prompt -> image	条件可用，仅模型明确支持 `mask` 时使用

图片编辑入口

POST https://tapapi.ai/v1/images/edits

这个接口使用 multipart/form-data。常见字段如下：

字段	类型	说明
`model`	string	模型名，必须是明确支持图片编辑的模型
`image`	file	输入图片；部分模型可用 `image[]` 传多张
`prompt`	string	编辑指令
`mask`	file	可选，仅在模型支持局部重绘时使用
`n`	integer	生成张数，建议先用 `1`
`size`	string	输出尺寸，取决于具体模型
`response_format`	string	`url` 或 `b64_json`

schema 里出现 mask 或 image[] 不代表所有模型都支持。以控制台可见模型、模型详情页和小样本测试为准。

cURL 示例

curl https://tapapi.ai/v1/images/edits \
  -H "Authorization: Bearer sk-xxx" \
  -F "model=gpt-image-1" \
  -F "image=@product.png" \
  -F "prompt=replace the background with a clean white ecommerce studio" \
  -F "response_format=url"

如果模型支持局部重绘，可以额外传 mask：

curl https://tapapi.ai/v1/images/edits \
  -H "Authorization: Bearer sk-xxx" \
  -F "model=gpt-image-1" \
  -F "image=@product.png" \
  -F "mask=@mask.png" \
  -F "prompt=change only the background to a warm kitchen scene" \
  -F "response_format=url"

生产接入建议

先确认模型明确支持图片编辑，再开放给用户
默认 n: 1，每张结果单独记录状态和成本
保存原图、prompt、模型名、返回图片、错误码、X-Oneapi-Request-Id 和业务 task_id
结果返回后尽快转存到自己的对象存储
对 400 / 422 不重试，优先修正字段、图片格式或 prompt
对临时 5xx / network timeout 只做有限重试
不要把 image_urls、mask、image[] 写成所有模型通用字段

验收方式

验收项	标准
支持范围	目标模型明确支持 `/v1/images/edits` 或对应编辑协议
输入文件	图片格式、大小、数量和 mask 规则已通过小样本验证
返回处理	同时兼容 `url` 和 `b64_json`，并检查 `data.length`
计费排查	每次请求保存业务 `task_id` 和 `X-Oneapi-Request-Id`
失败处理	400/422 不重试，临时错误有限重试并保留原始错误

如果只是从文字生成图片，请使用文生图。图生图规划说明见图生图，多参考图说明见多参考图。

基础能力

调用方式

接口参考

能力区别

图片编辑入口

cURL 示例

生产接入建议

验收方式

​能力区别

​图片编辑入口

​cURL 示例

​生产接入建议

​验收方式

能力区别

图片编辑入口

cURL 示例

生产接入建议

验收方式