# 编辑图像（OpenAI 兼容）
> 在已有图片上做整体或局部修改
> 请求体与生成接口相同，区别是必须提供 `image`
> 同步返回，一次响应给出结果
`POST /v1/images/edits`
## 认证
- `Authorization` (string / 必填) — 所有接口均使用 Bearer Token 进行认证。 Seedream 系列的接口需要在 [ark 站](https://ark.oairoute.com/) 单独获取 Key，与 api 站的 Key 不通用。 请求时在请求头中添加： ```http Authorization: Bearer YOUR_ARK_KEY ```
## 请求结构
请求体与[生成图像](openai.html)完全相同，唯一区别是必须提供至少一张参考图，通过 `image` 字段传入。
用 `multipart/form-data` 上传源图文件，或用 JSON 把 `image` 设为 URL 或 `data:` URI。
本接口**没有**独立的蒙版字段。需要只改局部时，改用生成接口的坐标编辑：在 `prompt` 里写 `<bbox>` 或 `[x1, y1, x2, y2]` 指定区域。
## 支持的场景
| 场景 | 字段组合 |
|---|---|
| 整体重绘 | `image` + `prompt` |
| 多图参考 | `image`（2 到 10 张数组）+ `prompt` |
| 局部修改 | `image` + `prompt` 内带坐标标记 |
| 上传文件 | `multipart/form-data`，`image` 传文件 |
## 请求参数
- `model` (string / 必填) — 图像模型 ID，必须写全名。取值见下方模型列表。
- `image` (string | string[] / 必填) — 待编辑的底图。公网 URL、`data:image/<格式>;base64,...`，或用 multipart 直接上传文件。格式标识须小写，最多 10 张，单张不超过 30MB。
- `prompt` (string / 条件必填) — 编辑描述。写清要改什么、改成什么样，不要重复描述没变的部分。`layer_decomposition` 为 `true` 时可不传。
- `size` (string / 可选) — 输出尺寸，档位 `1K`、`1.5K`、`2K`，或具体像素 `宽x高`，默认 `2K`。
- `response_format` (string / 可选) — `url`（默认，24 小时有效）或 `b64_json`。
- `watermark` (boolean / 可选) — 默认 `true`。需要无水印必须显式传 `false`。
- `output_format` (string / 可选) — `jpeg`（默认）或 `png`。
- `background` (string / 可选) — `transparent` 配合 `output_format: png` 可保留透明背景，要求恰好一张参考图。
- `seed` (integer / 可选) — 随机种子，`-1` 为随机。
- `guidance_scale` (number / 可选) — 提示词遵循强度。
- `n` (integer / 可选) — 只能是 `1`，传大于 1 会返回 400。
- `layer_decomposition` (boolean / 可选) — 图层拆分，要求恰好一张参考图。
- `stream` (boolean / 可选) — 不支持，传 `true` 会被拒绝。
## 用 multipart 上传本地文件
请求体可以走 `multipart/form-data`，用文件而非 URL 提交底图。所有标量字段都是字符串。
```bash
curl --request POST \
  --url 'https://ark.oairoute.com/v1/images/edits' \
  --header 'Authorization: Bearer YOUR_ARK_KEY' \
  --form 'model=doubao-seedream-5-0-pro-260628' \
  --form 'image=@room.png' \
  --form 'prompt=把这张照片改成夜景，增加霓虹灯氛围' \
  --form 'size=2K'
```
## 局部修改怎么做
本接口没有 `mask`。要只改画面中的一块区域，把区域写进提示词：
- 框选：`把框 [225, 442, 796, 1414] 内的区域替换成一把红色纸伞`
- 或在图片上先画好标记再上传，用自然语言描述要改的地方

坐标是该图的像素坐标，原点在左上角。模型只处理描述到的区域，其余保持不变。
## 编辑技巧
**提示词描述目标状态。** 与其写「把红衣服改成蓝衣服」，不如写「人物穿蓝色外套，其余不变」。
**保留构图。** 希望整体风格不动、只微调细节时，在提示词里强调「保持构图、光线与人物不变」。
**多轮编辑会累积失真。** 每次编辑都重新编码，反复五次以上画质会明显下降。需要多步修改时尽量一次说清，或从原图重新开始。
## 响应
同步返回，结构与[生成图像](openai.html)一致：
```json
{
  "data": [
    {
      "url": "https://ark-content-generation-v2-cn-beijing.tos-cn-beijing.volces.com/seedream/edit-xxx.jpeg",
      "size": "2048x2048",
      "output_format": "jpeg"
    }
  ],
  "created": 1757469067,
  "usage": {
    "generated_images": 1,
    "input_images": 1,
    "output_tokens": 15908,
    "total_tokens": 15908
  }
}
```
- `data[].url` (string) — 图片地址，`response_format` 为 `url` 时返回，24 小时有效。
- `data[].b64_json` (string) — `response_format` 为 `b64_json` 时返回。
- `data[].size` (string) — 实际像素尺寸。
- `data[].output_format` (string) — 文件格式。
- `usage.input_images` (integer) — 实际接收的参考图张数。
> **Note:** 
> 从第二张参考图起额外计费，`usage.input_images` 是计费依据。失败自动全额退款。
## 错误码
| HTTP | 含义 |
|---|---|
| 400 | 参数错误，type 为 invalid_request_error |
| 401 | Token 缺失或无效，type 为 authentication_error |
| 429 | 触发限流 |
常见 400 原因：没有传 `image`；`image` 不是可访问的地址或 Base64 格式标识未小写；`n` 大于 1；参考图超过 10 张。
更多状态码与重试建议见[错误码与限流](../../../support/errors.html)，常见报错的排查步骤见[常见问题](../../../support/faq.html)。
## 支持的模型列表
以下图像模型均支持参考图编辑，清单只列各厂商最新一代，实际可用范围以你的账号分组为准：
:::models image
> **Note:** 完整模型目录（含价格、分辨率上限）可读取 `GET https://ark.oairoute.com/api/pricing`。
## 使用示例
### 整体重绘
只传原图与提示词，模型会在保留主体构图的前提下重画整张图。适合换风格、换材质这类改动。
### 返回 Base64
需要把结果直接存进数据库或内网服务时，用 `b64_json` 避免二次下载。
**整体重绘{Full redraw}::cURL**
```
curl --request POST \
  --url 'https://ark.oairoute.com/v1/images/edits' \
  --header 'Authorization: Bearer YOUR_ARK_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "doubao-seedream-5-0-pro-260628",
  "image": "https://example.com/room.jpg",
  "prompt": "把房间改成北欧极简风格，浅色木地板，白墙",
  "size": "2K"
}'
```
**整体重绘{Full redraw}::Python**
```
import requests
url = "https://ark.oairoute.com/v1/images/edits"
headers = {
    "Authorization": "Bearer YOUR_ARK_KEY",
    "Content-Type": "application/json",
}
payload = {
    "model": "doubao-seedream-5-0-pro-260628",
    "image": "https://example.com/room.jpg",
    "prompt": "把房间改成北欧极简风格，浅色木地板，白墙",
    "size": "2K",
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**整体重绘{Full redraw}::JavaScript**
```
const res = await fetch("https://ark.oairoute.com/v1/images/edits", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_ARK_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "doubao-seedream-5-0-pro-260628",
    image: "https://example.com/room.jpg",
    prompt: "把房间改成北欧极简风格，浅色木地板，白墙",
    size: "2K",
  }),
});
console.log(await res.json());
```
**坐标局部修改{Coordinate edit}::cURL**
```
curl --request POST \
  --url 'https://ark.oairoute.com/v1/images/edits' \
  --header 'Authorization: Bearer YOUR_ARK_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "doubao-seedream-5-0-pro-260628",
  "image": "https://example.com/desk.jpg",
  "prompt": "把框 [320, 180, 640, 520] 内的杯子换成一本摊开的书",
  "size": "2K"
}'
```
**坐标局部修改{Coordinate edit}::Python**
```
import requests
url = "https://ark.oairoute.com/v1/images/edits"
headers = {
    "Authorization": "Bearer YOUR_ARK_KEY",
    "Content-Type": "application/json",
}
payload = {
    "model": "doubao-seedream-5-0-pro-260628",
    "image": "https://example.com/desk.jpg",
    "prompt": "把框 [320, 180, 640, 520] 内的杯子换成一本摊开的书",
    "size": "2K",
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**坐标局部修改{Coordinate edit}::JavaScript**
```
const res = await fetch("https://ark.oairoute.com/v1/images/edits", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_ARK_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "doubao-seedream-5-0-pro-260628",
    image: "https://example.com/desk.jpg",
    prompt: "把框 [320, 180, 640, 520] 内的杯子换成一本摊开的书",
    size: "2K",
  }),
});
console.log(await res.json());
```
**内联 Base64{Inline Base64}::cURL**
```
curl --request POST \
  --url 'https://ark.oairoute.com/v1/images/edits' \
  --header 'Authorization: Bearer YOUR_ARK_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "doubao-seedream-5-0-flash-260915",
  "image": "https://example.com/room.jpg",
  "prompt": "把房间改成北欧极简风格",
  "size": "1K",
  "response_format": "b64_json"
}'
```
**内联 Base64{Inline Base64}::Python**
```
import requests
url = "https://ark.oairoute.com/v1/images/edits"
headers = {
    "Authorization": "Bearer YOUR_ARK_KEY",
    "Content-Type": "application/json",
}
payload = {
    "model": "doubao-seedream-5-0-flash-260915",
    "image": "https://example.com/room.jpg",
    "prompt": "把房间改成北欧极简风格",
    "size": "1K",
    "response_format": "b64_json",
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**内联 Base64{Inline Base64}::JavaScript**
```
const res = await fetch("https://ark.oairoute.com/v1/images/edits", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_ARK_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "doubao-seedream-5-0-flash-260915",
    image: "https://example.com/room.jpg",
    prompt: "把房间改成北欧极简风格",
    size: "1K",
    response_format: "b64_json",
  }),
});
console.log(await res.json());
```
**200 整体重绘{Full redraw}**
```
{
  "data": [
    {
      "url": "https://ark-content-generation-v2-cn-beijing.tos-cn-beijing.volces.com/seedream/edit-xxx.jpeg",
      "size": "2048x2048",
      "output_format": "jpeg"
    }
  ],
  "created": 1757469067,
  "usage": {
    "generated_images": 1,
    "input_images": 1,
    "output_tokens": 15908,
    "total_tokens": 15908
  }
}
```
**200 坐标局部修改{Coordinate edit}**
```
{
  "data": [
    {
      "url": "https://ark-content-generation-v2-cn-beijing.tos-cn-beijing.volces.com/seedream/edit-region.jpeg",
      "size": "2048x2048",
      "output_format": "jpeg"
    }
  ],
  "created": 1757469067,
  "usage": {
    "generated_images": 1,
    "input_images": 1,
    "output_tokens": 15908,
    "total_tokens": 15908
  }
}
```
**200 内联 Base64{Inline Base64}**
```
{
  "data": [
    {
      "b64_json": "/9j/4AAQSkZJRgABAQAAAQABAAD...",
      "size": "1024x1024",
      "output_format": "jpeg"
    }
  ],
  "created": 1757469067,
  "usage": {
    "generated_images": 1,
    "input_images": 1,
    "output_tokens": 4096,
    "total_tokens": 4096
  }
}
```