编辑图像（Images）

按 OpenAI Images API 形态编辑图片：POST /images/edits（multipart/form-data），上传参考图与可选 mask，成功响应为 created + data[]。

改图是携带输入图的生图请求，不是独立第三套修改接口。无参考图的文生图见 创建图像（Images）；统一契约带参考图见 创建图像生成（chat）。

模型 ID 见 获取模型（modality=image）或 模型广场。同一模型不一定支持 mask 局部重绘。

---

Endpoint

Method	URL	说明
POST	{TRINITY_BASE_URL}/images/edits	参考图改图 / 可选 mask，同步等待

---

Base URL

项	值
Base URL	https://api.trinitydesk.ai/v1
协议	HTTPS

export TRINITY_BASE_URL="https://api.trinitydesk.ai/v1"
export TRINITY_API_KEY="xh-..."

---

Headers

Header	必填	说明
Authorization	是	Bearer <TRINITY_API_KEY>
Content-Type	是	multipart/form-data（由客户端自动带 boundary）

---

请求示例

curl -sS "${TRINITY_BASE_URL}/images/edits" \
  -H "Authorization: Bearer ${TRINITY_API_KEY}" \
  -F "model=gpt-image-2" \
  -F "prompt=Make the otter wear a small hat" \
  -F "image=@/path/to/input.png" \
  -F "size=1024x1024" \
  -F "n=1"

带 mask：

curl -sS "${TRINITY_BASE_URL}/images/edits" \
  -H "Authorization: Bearer ${TRINITY_API_KEY}" \
  -F "model=gpt-image-2" \
  -F "prompt=Replace the sky with sunset colors" \
  -F "image=@/path/to/input.png" \
  -F "mask=@/path/to/mask.png" \
  -F "size=1024x1024" \
  -F "n=1"

---

请求体字段

表单字段（multipart/form-data）：

字段	类型	必填	说明
model	string	是	生图模型 ID
prompt	string	是	编辑说明
image	file	是	输入图片；可多文件（字段名 image 或 image[]，上限以模型能力为准）
mask	file	否	局部重绘遮罩；模型不支持时勿传
n	integer	否	生成张数
size	string	否	像素尺寸，如 1024x1024
quality	string	否	质量档位；以模型能力为准
output_format	string	否	文件格式：png / jpeg / webp
background	string	否	背景控制；以模型能力为准
moderation	string	否	审核档位；以模型能力为准
output_compression	integer	否	jpeg/webp 压缩比
response_format	string	否	url（默认）或 b64_json
stream	boolean	否	true 不被接受

---

返回字段

与 创建图像（Images） 相同：created、data[].url 或 data[].b64_json、可选 usage。

响应头可能包含 X-Xh-Image-Task-Id。超时后查询见 查询图像任务。

---

返回示例

{
  "created": 1777777777,
  "data": [
    {
      "url": "https://example.cos.ap-singapore.myqcloud.com/trinity-image/edit-demo.png"
    }
  ]
}

错误为 error 对象，见 错误与调试。

---

Python 示例

import os
import requests

base = os.environ["TRINITY_BASE_URL"]
key = os.environ["TRINITY_API_KEY"]

with open("/path/to/input.png", "rb") as image_file:
    r = requests.post(
        f"{base}/images/edits",
        headers={"Authorization": f"Bearer {key}"},
        data={
            "model": "gpt-image-2",
            "prompt": "Make the otter wear a small hat",
            "size": "1024x1024",
            "n": "1",
        },
        files={"image": ("input.png", image_file, "image/png")},
        timeout=300,
    )
r.raise_for_status()
print(r.json())

---

相关

• 创建图像（Images）
• 创建图像生成（chat）
• 查询图像任务
• 高级参数 · 生图
• 获取模型
• 错误与调试