# 豆包 Seedream 生图 API：尺寸、组图、改图参数与报错

Source: https://ofox.ai/zh/docs/develop/models/seedream

字节跳动的豆包图像模型，共三款，通过 OpenAI 兼容接口 `/v1/images/generations` 调用，文生图与改图均使用该端点。

## 模型选择

**要点**:5.0 Pro 每次生成一张，支持 1K 至 2K；组图与 4K 由 5.0 Lite、4.5 提供。

- **Seedream 5.0 Pro**(旗舰): 支持 1K 尺寸; 不支持组图与 4k 预设 — doubao-seedream-5.0-pro
- **Seedream 5.0 Lite**: 支持组图与 4K; 最低 2K — doubao-seedream-5.0-lite
- **Seedream 4.5**(上一代): 支持组图与 n 多张; 最低 2K — doubao-seedream-4.5

**模型 ID（调用时原样复制）**

- 5.0 Pro: `volcengine/doubao-seedream-5.0-pro` — 旗舰，支持 1K

实时价格请参阅[模型页](https://ofox.ai/zh/models/volcengine/doubao-seedream-5.0-pro)。

## 文生图

**Python**

```python filename="seedream.py"
import base64
from openai import OpenAI

client = OpenAI(api_key="YOUR_OFOX_API_KEY", base_url="https://api.ofox.ai/v1", timeout=600)

resp = client.images.generate(
    model="volcengine/doubao-seedream-5.0-pro",
    prompt="白色桌面上的一个红苹果",
    size="2560x1440",
)

with open("output.jpg", "wb") as f:
    f.write(base64.b64decode(resp.data[0].b64_json))
```

**cURL**

```bash filename="Terminal"
curl https://api.ofox.ai/v1/images/generations \
  --max-time 600 \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "volcengine/doubao-seedream-5.0-pro",
    "prompt": "白色桌面上的一个红苹果",
    "size": "2560x1440"
  }' | jq -r '.data[0].b64_json' | base64 --decode > output.jpg
```

输出格式固定为 **JPEG**，保存时请使用 `.jpg` 扩展名。默认返回 base64；传入 `"response_format": "url"` 可改为返回图片链接。

## 尺寸（size）

**要点**:4.5 与 5.0 Lite 最低为 2K（3,686,400 像素），`1k` 与 1024×1024 均会被拒绝。

`size` 支持两种写法：

- **分辨率档位** `1k`、`2k`、`4k`（不区分大小写）：仅指定分辨率，**比例由模型根据提示词决定**。实测 4.5 传入 `2k` 时，输出既有 2048×2048，也有 1664×2496。
- **精确宽高** `宽x高`：比例固定，须满足下表的像素范围。

| | 5.0 Pro | 5.0 Lite | 4.5 |
|---|---|---|---|
| 最少像素 | 921,600（如 1280×720） | 3,686,400（如 2560×1440） | 3,686,400 |
| 最多像素 | — | — | 16,777,216（4096×4096） |
| `1k` | 支持，实测 1152×864 | 不支持 | 不支持 |
| `2k` | 支持 | 支持 | 支持 |
| `4k` | 不支持 | 支持，实测 4096×4096 | 支持 |
| 不传 `size` | 实测 2368×1776 | — | — |

「—」表示本次未实测，请以[火山方舟官方文档](https://www.volcengine.com/docs/82379)为准。

**常用的合法宽高**（满足 4.5 和 5.0 Lite 的最低像素）：

| 比例 | 宽高 |
|---|---|
| 1:1 | `2048x2048` |
| 16:9 | `2560x1440` |
| 9:16 | `1440x2560` |
| 4:3 | `2304x1728` |
| 3:4 | `1728x2304` |

## 改图与多图参考

**要点**:参考图使用 `image` 字段，而非 `input_images`；不支持 `/v1/images/edits`。

**Python**

```python filename="seedream_edit.py"
import base64
from openai import OpenAI

client = OpenAI(api_key="YOUR_OFOX_API_KEY", base_url="https://api.ofox.ai/v1", timeout=600)

with open("apple.jpg", "rb") as f:
    ref = "data:image/jpeg;base64," + base64.b64encode(f.read()).decode()

resp = client.images.generate(
    model="volcengine/doubao-seedream-5.0-pro",
    prompt="把苹果改成紫色，其他保持不变",
    size="2k",
    extra_body={"image": [ref]},
)

with open("apple_purple.jpg", "wb") as f:
    f.write(base64.b64decode(resp.data[0].b64_json))
```

**cURL**

```bash filename="Terminal"
# base64 很长，直接拼进命令行会报 Argument list too long，先写进文件
printf 'data:image/jpeg;base64,%s' "$(base64 < apple.jpg | tr -d '\n')" > apple.b64
jq -n --rawfile img apple.b64 '{
  model: "volcengine/doubao-seedream-5.0-pro",
  prompt: "把苹果改成紫色，其他保持不变",
  size: "2k",
  image: [$img]
}' > body.json

curl https://api.ofox.ai/v1/images/generations \
  --max-time 600 \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json | jq -r '.data[0].b64_json' | base64 --decode > apple_purple.jpg
```

- `image` 为数组，每项为图片 URL 或以 `data:image/...;base64,` 开头的字符串。多张参考图依次放入数组，并在提示词中说明每张图片的作用。
- `input_images` 为 Qwen-Image 专用字段，Seedream 不支持。
- Seedream 不支持 `/v1/images/edits`，改图请使用本节的 `image` 字段。

## 组图与多张

**要点**:5.0 Lite 与 4.5 支持单次返回多张；5.0 Pro 每次请求仅生成一张。

| 写法 | 5.0 Pro | 5.0 Lite | 4.5 |
|---|---|---|---|
| `n: 2` | 返回 400 | — | 实测返回 2 张 |
| `sequential_image_generation: "auto"` | 返回 400 | 实测返回 3 张 | 实测只返回 1 张 |

组图示例：

```json
{
  "model": "volcengine/doubao-seedream-5.0-lite",
  "prompt": "生成 3 张独立的图：同一只狐狸分别在春天、夏天、秋天",
  "size": "2k",
  "sequential_image_generation": "auto",
  "sequential_image_generation_options": { "max_images": 3 }
}
```

- `auto` 表示**由模型决定**生成张数，`max_images` 仅为上限。实测相同请求下，4.5 将三格漫画合成在一张图中，仅返回 1 张。如需固定张数，请在提示词中明确写出「生成 N 张独立的图片」。
- 每张图片单独计费，`usage.output_tokens` 为全部图片的合计。

## 水印
实测通过 OfoxAI 调用时**默认不带水印**，无需额外传参。

## 耗时
实测 2K 约 12 至 40 秒，3 张组图约 76 秒。客户端超时建议设置为 300 秒以上。

## 常见报错

**要点**:尺寸相关报错最为常见，请先查看报错中的像素数。

| 报错原文（节选） | 原因 | 处理方法 |
|---|---|---|
| `image size must be at least 3686400 pixels` | 4.5 或 5.0 Lite 的尺寸低于 2K | 改为 `2k` 或 `2560x1440` 等，见[尺寸](#size) |
| `image area must be at least 921600 pixels` | 5.0 Pro 的尺寸低于 1280×720 | 增大尺寸 |
| `image size must be at most 16777216 pixels` | 超过 4096×4096 | 减小尺寸 |
| `the specified size is not supported for model doubao-seedream-4-5` | 4.5 传入了 `1k` | 改为 `2k` 或 `4k` |
| `must be 'WIDTHxHEIGHT' or a supported size preset` | 5.0 Pro 传入了 `4k` | 改为 `2k` 或精确宽高 |
| `size must be one of 'WIDTHxHEIGHT', '1k', '2k', or '4k'` | 传入了 `8K`、`2048` 等无效值 | 按上述四种格式填写 |
| `the parameter sequential_image_generation is not supported by the current model` | 5.0 Pro 传入了 `n` 或组图参数 | 删除 `n`；需要多张时请并发发起多次请求 |
| `the parameter output_format is not supported by the current model` | 传入了 `output_format` | 删除该参数，输出格式固定为 JPEG |
| `does not support the /v1/images/edits endpoint` | 调用了改图端点 | 改用 `/v1/images/generations` 的 [image 字段](#edit) |
| 参考图未生效 | 使用了 `input_images` | 改用 `image` |

报错原文末尾的 `Request id: 0217…` 为上游请求号，联系技术支持时请与响应中的 `request_id` 一并提供。

报错原文

```text
The parameter `size` specified in the request is not valid: image size must be at least 3686400 pixels.
The parameter `size` specified in the request are not valid: image area must be at least 921600 pixels.
The parameter `size` specified in the request is not valid: image size must be at most 16777216 pixels.
The parameter `size` specified in the request is not valid: the specified size is not supported for model doubao-seedream-4-5.
The parameter `size` specified in the request are not valid: must be 'WIDTHxHEIGHT' or a supported size preset.
The parameter `size` specified in the request is not valid: size must be one of 'WIDTHxHEIGHT', '1k', '2k', or '4k'.
The parameter `sequential_image_generation` specified in the request are not valid: the parameter `sequential_image_generation` is not supported by the current model.
The parameter `output_format` specified in the request is not valid: the parameter `output_format` is not supported by the current model.
```

## 官方文档
官方文档描述的是直连火山方舟时的行为；通过 OfoxAI 调用时，以本页实测结论为准。

- [火山方舟文档中心](https://www.volcengine.com/docs/82379)

## 常见问题

**Seedream 报错 image size must be at least 3686400 pixels 怎么办？**

Seedream 4.5 和 5.0 Lite 的最低尺寸是 2K，即 3,686,400 像素，1024x1024 和 1k 均不满足要求。改为 2k，或 2048x2048、2560x1440、1440x2560 等宽高。需要较小尺寸时请使用 5.0 Pro，它最低 921,600 像素（1280x720），也支持 1k。

**Seedream 怎么改图？用 input_images 没有效果？**

Seedream 的参考图字段是 image（数组，每项是图片 URL 或 data:image 开头的 base64），不是 input_images，input_images 是 Qwen-Image 的字段。另外 Seedream 不支持 /v1/images/edits，改图同样使用 /v1/images/generations。

**Seedream 组图怎么一次生成多张？**

传 sequential_image_generation: "auto" 和 sequential_image_generation_options.max_images。auto 表示由模型决定张数，max_images 是上限，在提示词中写明「生成 N 张独立的图」更稳定。5.0 Lite 和 4.5 支持，5.0 Pro 不支持。

**Seedream 5.0 Pro 传 n 报 sequential_image_generation is not supported？**

5.0 Pro 不支持一次生成多张，n 和组图参数都会返回此报错。删除 n，如需多张，请并发发起多次请求。

**Seedream 生成的图片有水印吗？**

通过 OfoxAI 调用，实测默认不带水印，无需额外传参。

**Seedream 能输出 PNG 吗？**

不能，输出固定为 JPEG。传入 output_format 会返回 400，删除该参数即可。

**Seedream 的 size 传 2k 为什么比例不固定？**

1k、2k、4k 只指定分辨率，比例由模型根据提示词决定。需要固定比例请传精确宽高，如 2560x1440。