火山引擎图片生成
使用火山方舟 (Ark) 平台的 Seedream 系列模型生成高质量图片。
支持的模型
| 模型 ID | 名称 | 特点 |
|---|---|---|
doubao-seedream-3-0-t2i-250115 | Seedream 3.0 | 轻量级，速度快 |
doubao-seedream-4-0-t2i-250115 | Seedream 4.0 | 标准质量 |
doubao-seedream-4-5-251128 | Seedream 4.5 | 最新高质量 (默认) |
快速开始
1. 配置 API Key
在 skill 目录的 .env 文件中配置：
VOLCENGINE_IMAGE_API_KEY=你的-api-key
VOLCENGINE_IMAGE_ENDPOINT=https://ark.cn-beijing.volces.com/api/v3
VOLCENGINE_IMAGE_DEFAULT_MODEL=doubao-seedream-4-5-251128或者在环境变量中设置：
export VOLCENGINE_IMAGE_API_KEY=你的-api-key2. 生成图片
# 基础生成
python3 scripts/generate.py "一只可爱的猫咪" -o cat.png
# 指定比例
python3 scripts/generate.py "科幻城市夜景" -r 16:9 -o city.png
# 指定尺寸 (2K)
python3 scripts/generate.py "山水画" -W 2048 -H 2048 -o landscape.png
# 使用特定模型
python3 scripts/generate.py "赛博朋克风格" -m doubao-seedream-4-0-t2i-250115 -o cyber.png
# 生成多张
python3 scripts/generate.py "不同角度的跑车" -n 4 -o car.png使用示例
示例 1: 基础文生图
cd ~/clawd/skills/volcengine-image-gen
python3 scripts/generate.py "一只可爱的橘猫在窗台上晒太阳，水彩风格" -o cat.png示例 2: 指定比例
python3 scripts/generate.py "未来城市夜景，霓虹灯，赛博朋克" -r 16:9 -o cyberpunk.png支持的比例：
1:1- 正方形16:9/9:16- 宽屏/竖屏4:3/3:4- 标准比例2:3/3:2- 照片比例
示例 3: Python 调用
import sys
sys.path.insert(0, '/Users/xdrshjr/clawd/skills/volcengine-image-gen/scripts')
from generate import generate_image
# 生成图片
paths = generate_image(
prompt="一只可爱的猫咪在花园里玩耍",
ratio="1:1",
output_path="cat.png"
)
print(f"图片已保存: {paths[0]}")命令行参数
| 参数 | 说明 | 默认值 |
|---|---|---|
prompt | 图片描述提示词 | 必填 |
-o, --output | 输出文件路径 | 自动生成 |
-m, --model | 模型名称 | Seedream 4.5 |
-r, --ratio | 图片比例 | 1:1 |
-W, --width | 图片宽度 | 根据比例计算 |
-H, --height | 图片高度 | 根据比例计算 |
-n, --number | 生成数量 (1-4) | 1 |
--no-watermark | 不添加水印 | - |
--url | 返回 URL 而不是下载 | - |
--list-models | 列出支持的模型 | - |
--debug | 开启调试模式 | - |
尺寸要求
- 最小像素: 3,686,400 (约 1920x1920)
- 推荐尺寸: 2048x2048 (2K)
- 如果指定的比例尺寸不满足最小像素，会自动放大
环境变量
| 变量名 | 说明 | 必填 |
|---|---|---|
VOLCENGINE_IMAGE_API_KEY | 火山引擎 API Key | ✅ |
VOLCENGINE_IMAGE_ENDPOINT | API 端点 | ❌ |
VOLCENGINE_IMAGE_DEFAULT_MODEL | 默认模型 | ❌ |
获取 API Key
- 访问 火山方舟控制台
- 点击右上角 API Key 管理
- 创建新的 API Key
- 复制 Key 并配置到
.env文件
安装依赖
cd ~/clawd/skills/volcengine-image-gen
pip3 install -r requirements.txt故障排除
API Key 无效
AuthenticationError: The API key format is incorrect解决: 确认使用的是火山方舟 (Ark) 的 API Key，不是语音合成的 Access Token。
尺寸太小
InvalidParameter: image size must be at least 3686400 pixels解决: 使用更大的尺寸，如 2048x2048 或更大的比例。
网络超时
网络请求失败解决: 图片生成可能需要 30-60 秒，请检查网络连接。
提示词技巧
有效的提示词结构
[主体], [细节描述], [风格], [光线], [构图], [色彩]示例
一只可爱的橘猫，趴在窗台上晒太阳，毛发柔软蓬松，
水彩画风格，柔和的自然光线，温馨的氛围，
暖色调，细节丰富，高清画质常用风格关键词
- 写实: photorealistic, realistic, detailed
- 动漫: anime, manga, cartoon style
- 油画: oil painting, classical art
- 水彩: watercolor, soft colors
- 赛博朋克: cyberpunk, neon lights, futuristic
- 中国风: Chinese traditional style, ink wash painting