volcengine-image-gen

Volcano Engine Image Generation

Use the Volcano Ark (Ark) platform's Seedream series models to generate high-quality images.

Supported Models

Model ID	Name	Features
`doubao-seedream-3-0-t2i-250115`	Seedream 3.0	Lightweight, fast
`doubao-seedream-4-0-t2i-250115`	Seedream 4.0	Standard quality
`doubao-seedream-4-5-251128`	Seedream 4.5	Latest high quality (default)

Quick Start

1. Configure API Key

In the skill directory's .env file, configure:

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

Or set it in an environment variable:

export VOLCENGINE_IMAGE_API_KEY=你的-api-key

2. Generate Images

# 基础生成
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

Usage Examples

Example 1: Basic Text-to-Image

cd ~/clawd/skills/volcengine-image-gen
python3 scripts/generate.py "一只可爱的橘猫在窗台上晒太阳，水彩风格" -o cat.png

Example 2: Specify Aspect Ratio

python3 scripts/generate.py "未来城市夜景，霓虹灯，赛博朋克" -r 16:9 -o cyberpunk.png

Supported aspect ratios:

1:1 - Square
16:9 / 9:16 - Widescreen/Portrait
4:3 / 3:4 - Standard ratio
2:3 / 3:2 - Photo ratio

Example 3: Python Call

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]}")

Command-Line Arguments

Argument	Description	Default Value
`prompt`	Image description prompt	Required
`-o, --output`	Output file path	Auto-generated
`-m, --model`	Model name	Seedream 4.5
`-r, --ratio`	Image aspect ratio	1:1
`-W, --width`	Image width	Calculated based on aspect ratio
`-H, --height`	Image height	Calculated based on aspect ratio
`-n, --number`	Number to generate (1-4)	1
`--no-watermark`	Do not add watermark	-
`--url`	Return URL instead of downloading	-
`--list-models`	List supported models	-
`--debug`	Enable debug mode	-

Size Requirements

Minimum pixels: 3,686,400 (about 1920x1920)
Recommended size: 2048x2048 (2K)
If the specified aspect ratio size does not meet the minimum pixels, it will be automatically enlarged

Environment Variables

Variable Name	Description	Required
`VOLCENGINE_IMAGE_API_KEY`	Volcano Engine API Key	✅
`VOLCENGINE_IMAGE_ENDPOINT`	API endpoint	❌
`VOLCENGINE_IMAGE_DEFAULT_MODEL`	Default model	❌

Get API Key

Visit Volcano Ark Console
Click in the top right corner API Key Management
Create a new API Key
Copy the Key and configure it in the .env file

Install Dependencies

cd ~/clawd/skills/volcengine-image-gen
pip3 install -r requirements.txt

Troubleshooting

Invalid API Key

AuthenticationError: The API key format is incorrect

Solution: Confirm that you are using the Volcano Ark (Ark) API Key, not the Access Token for speech synthesis.

Size Too Small

InvalidParameter: image size must be at least 3686400 pixels

Solution: Use a larger size, such as 2048x2048 or a larger aspect ratio.

Network Timeout

网络请求失败

Solution: Image generation may take 30-60 seconds; please check your network connection.

Prompt Tips

Effective Prompt Structure

[主体], [细节描述], [风格], [光线], [构图], [色彩]

Example

一只可爱的橘猫，趴在窗台上晒太阳，毛发柔软蓬松，
水彩画风格，柔和的自然光线，温馨的氛围，
暖色调，细节丰富，高清画质

Common Style Keywords

Realistic: photorealistic, realistic, detailed
Anime: anime, manga, cartoon style
Oil painting: oil painting, classical art
Watercolor: watercolor, soft colors
Cyberpunk: cyberpunk, neon lights, futuristic
Chinese style: Chinese traditional style, ink wash painting

About this skill