Seedream 图像生成

通过火山引擎 Doubao-Seedream API 生成与编辑图像，使用脚本 {baseDir}/scripts/generate_image.py。

该能力封装了火山引擎 Ark 图像生成 API，支持文生图、图像编辑、多参考图融合、序列/分组生成、PNG 输出、提示词优化、网络搜索及流式输出。兼容 Seedream 5.0-lite（默认）、4.5 和 4.0 模型。

快速开始

# 文生图（最简形式）
uv run {baseDir}/scripts/generate_image.py --prompt "一只赛博朋克风格的猫"

# 图像编辑（需提供参考图）
uv run {baseDir}/scripts/generate_image.py --prompt "变为水墨画风格" --image "https://example.com/photo.jpg"

# 多参考图融合
uv run {baseDir}/scripts/generate_image.py --prompt "融合风格" --image "https://a.jpg" --image "https://b.jpg"

# 分组/序列生成
uv run {baseDir}/scripts/generate_image.py --prompt "四格漫画" --sequential --max-images 4

# 列出可用模型
uv run {baseDir}/scripts/generate_image.py --list-models

API 密钥

设置环境变量 VOLC_API_KEY，或通过 --api-key 参数传入。切勿在脚本中硬编码密钥。

export VOLC_API_KEY="your-key"
# 或
--api-key your-key

模型

默认模型：doubao-seedream-5-0-260128（5.0-lite）。可通过 --model 覆盖。

模型对比

模型选型建议

• 5.0-lite（默认） — 综合质量最优。唯一支持 PNG 输出、3K 分辨率和网络搜索的模型，适用于绝大多数任务。
• 4.5 — 高质量，风格略有差异，是 5.0-lite 的良好替代选择。
• 4.0 — 支持 --prompt-optimization fast 模式以加速生成，适合快速迭代；同时支持 1K 尺寸，可实现更小体积、更快响应的生成。

尺寸与分辨率

指定尺寸有两种方式（不可混用）：

方式一：预设尺寸（推荐用于大多数场景）：

--size 2K    # 2048×2048（默认）
--size 3K    # 3072×3072（仅 5.0-lite 支持）
--size 4K    # 4096×4096（所有模型均支持）
--size 1K    # 1024×1024（仅 4.0 支持）

方式二：像素格式（适用于自定义宽高比）：

--size 3840x2160    # 16:9 宽屏
--size 1080x1920    # 9:16 竖屏
--size 1200x1200    # 自定义正方形

分辨率对照表（预设尺寸 × 宽高比）

使用预设尺寸时，模型将根据提示词自动选择最优宽高比。如需精确控制，请使用像素格式。

像素格式约束

• 5.0-lite：总像素数 ∈ [3,686,400 ~ 16,777,216]，宽高比 ∈ [1/16 ~ 16]
• 4.5：总像素数 ∈ [3,686,400 ~ 16,777,216]，宽高比 ∈ [1/16 ~ 16]
• 4.0：总像素数 ∈ [921,600 ~ 16,777,216]，宽高比 ∈ [1/16 ~ 16]

示例：

• ✅ 3840x2160 → 8,294,400 像素，宽高比 1.78 → 所有模型均有效
• ✅ 2160x3840 → 同样像素数，宽高比 0.56 → 所有模型均有效
• ❌ 1500x1500 → 2,250,000 像素 < 最小值 3,686,400 → 对 5.0-lite/4.5 无效

参数说明

必需参数

• --prompt — 图像生成的文本描述。支持中文与英文。建议长度不超过 300 个中文字符或 600 个英文单词。

模型与尺寸

• --model — 模型 ID（默认：doubao-seedream-5-0-260128）
• --size — 预设尺寸（1K/2K/3K/4K）或像素格式（WIDTHxHEIGHT，默认：2K）

图像输入

• --image — 参考图像 URL 或 base64 编码字符串。可重复使用以传入多张图像（最多共 14 张），用于图像编辑与多参考图融合。

支持的输入格式：jpeg、png、webp、bmp、tiff、gif、heic、heif。
限制条件：单图最大 30MB，最大像素数 60MP（宽 × 高），宽高比范围 [1/16, 16]。

输出控制

• --output-format — jpeg（默认）或 png（仅 5.0-lite 支持）
• --response-format — url（默认，链接有效期 24 小时）或 b64_json（base64 编码）
• --watermark / --no-watermark — 启用/禁用 “AI生成” 水印（默认启用）

生成模式

• --sequential — 启用分组/序列生成（生成多张相关图像）
• --max-images — 序列模式下生成图像数量（取值范围 1–15，默认为 1）
• --stream — 启用流式输出（边生成边返回结果）
• --web-search — 启用网络搜索以获取实时信息（仅 5.0-lite 支持）。对应 API 参数 tools: [{type: "web_search"}]。

提示词增强

• --prompt-optimization — standard（所有模型）或 fast（仅 4.0 支持）。自动重写提示词以提升生成效果。

工具类参数

• --list-models — 列出所有可用 Seedream 模型及其能力
• --api-key — 火山引擎 API 密钥（或通过 VOLC_API_KEY 环境变量设置）

完整示例用例

1. 文生图（基础）

uv run {baseDir}/scripts/generate_image.py --prompt "充满活力的特写肖像，模特眼神犀利，头戴雕塑感帽子，色彩拼接丰富，Vogue杂志封面美学"

2. 文生图（指定尺寸）

# 4K 横屏
uv run {baseDir}/scripts/generate_image.py --prompt "壮丽的山川日出，金色阳光穿过云层" --size 4K

# 自定义宽屏
uv run {baseDir}/scripts/generate_image.py --prompt "赛博朋克城市夜景" --size 3840x2160

# 手机壁纸竖屏
uv run {baseDir}/scripts/generate_image.py --prompt "极简抽象艺术" --size 1080x1920

3. 图像编辑（单参考图）

uv run {baseDir}/scripts/generate_image.py 
  --prompt "保持模特姿势和构图不变，将服装材质从银色金属改为完全透明的清水" 
  --image "https://example.com/original.jpg"

4. 多参考图融合

# 融合 2 张图
uv run {baseDir}/scripts/generate_image.py 
  --prompt "将图1的服装换为图2的服装" 
  --image "https://example.com/person.jpg" 
  --image "https://example.com/clothing.jpg"

# 融合 3 张及以上图像
uv run {baseDir}/scripts/generate_image.py 
  --prompt "融合这三张图的风格特征，生成统一视觉" 
  --image "https://example.com/1.jpg" 
  --image "https://example.com/2.jpg" 
  --image "https://example.com/3.jpg"

5. 序列/分组生成

# 生成 4 张关联图像
uv run {baseDir}/scripts/generate_image.py 
  --prompt "生成一组电影级科幻写实风的4张影视分镜" 
  --sequential --max-images 4

# 带参考图的序列生成
uv run {baseDir}/scripts/generate_image.py 
  --prompt "参考这张图，生成同角色在早晨、中午、晚上的连续画面" 
  --image "https://example.com/character.jpg" 
  --sequential --max-images 3

6. PNG 输出

uv run {baseDir}/scripts/generate_image.py 
  --prompt "高清产品图，白色背景，专业摄影灯光" 
  --output-format png

7. 提示词优化

# standard 模式（质量更高，所有模型支持）
uv run {baseDir}/scripts/generate_image.py 
  --prompt "一只猫" 
  --prompt-optimization standard

# fast 模式（速度更快，仅 4.0 支持）
uv run {baseDir}/scripts/generate_image.py 
  --prompt "一只猫" 
  --model doubao-seedream-4-0-250828 
  --prompt-optimization fast

8. 网络搜索（实时信息，仅 5.0-lite）

# 天气预报图
uv run {baseDir}/scripts/generate_image.py 
  --prompt "制作一张上海未来5日的天气预报图，扁平化插画风格" 
  --web-search

# 当前热点事件
uv run {baseDir}/scripts/generate_image.py 
  --prompt "2026年最流行的时尚趋势海报" 
  --web-search

9. 去除水印（商用场景）

uv run {baseDir}/scripts/generate_image.py 
  --prompt "产品宣传图，专业商业摄影" 
  --no-watermark

提示词撰写建议

• 语言：支持中文与英文。复杂场景下英文通常略优于中文，但中文同样效果良好。
• 长度：建议不超过 300 个中文字符或 600 个英文单词；过长可能导致模型忽略部分细节。
• 具体性：越具体越好。例如：“赛博朋克风格的猫，霓虹灯光，雨夜街道，4K，电影感” 优于 “一只猫”。
• 风格关键词：添加风格术语以增强控制力：
  • 水墨画风格（ink painting）
  • 油画风格（oil painting）
  • 写实摄影（photorealistic）
  • 扁平化插画（flat illustration）
  • 电影感（cinematic）
  • 杂志封面（magazine cover）
• 结构化描述：对于复杂场景，建议按以下顺序组织提示词：主体 → 构图 → 风格 → 光影 → 画质

输出解析

脚本标准输出（stdout）中仅包含以下三者之一：

• MEDIA_URL: — 图像下载链接。有效期为 24 小时。 可直接用于 Markdown： ![description](url)
• MEDIA_B64: — Base64 编码图像数据（当指定 --response-format b64_json 时）
• ERROR: — 发生错误。请根据提示信息排查原因。

错误处理

工作流程

1. 解析用户图像请求，判断类型：文生图、图像编辑、多图融合或序列生成
2. 选择合适模型（默认优先选用 5.0-lite，除非有特定需求）
3. 确定尺寸：通用场景使用预设尺寸，需精确宽高比时使用像素格式
4. 构建并执行带相应参数的命令
5. 解析 stdout 输出，提取 MEDIA_URL: 或 MEDIA_B64:
6. 以 Markdown 图片或本地文件形式向用户展示结果
7. 若返回 URL，提醒用户链接 24 小时后过期，如需长期保存请立即下载

输入图像要求

• 格式：jpeg、png、webp、bmp、tiff、gif、heic、heif
• 单图大小上限：30MB
• 最大像素数：60,000,000（宽 × 高）
• 宽高比范围：[1/16, 16]
• 最小边长：每边大于 14 像素
• 单次请求最多图像数：14 张
• 总量限制：输入图像数 + 输出图像数 ≤ 15

调用频率限制

所有模型统一为 500 张图像/分钟（IPM）。批量操作请据此合理规划。

完整参考文档

详细 API 参数说明请参阅 references/REFERENCE.md。