volcengine-image-gen

Volcengine 画像生成

火山方舟（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-key

2. 画像を生成する

# 基础生成
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	Volcengine API Key	✅
VOLCENGINE_IMAGE_ENDPOINT	API エンドポイント	❌
VOLCENGINE_IMAGE_DEFAULT_MODEL	デフォルトモデル	❌

API Key の取得

1. 火山方舟コンソールにアクセスします。
2. 右上の API Key 管理をクリックします。
3. 新しい API Key を作成します。
4. 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

参考ドキュメント

• 火山方舟ドキュメント
• Seedream プロンプトガイド