Seedream Volcengine

SKILL.md

---
name: seedream-volcengine
description: Generate or edit images with Volcengine Seedream (Doubao). Use for image creation requests incl. text-to-image, image-to-image, multi-reference fusion, sequential/group generation, PNG output, prompt optimization, web search, streaming. Supports Seedream 5.0-lite / 4.5 / 4.0.
---

# Seedream Image Generation

Generate and edit images via Volcengine Doubao-Seedream API using `{baseDir}/scripts/generate_image.py`.

This skill wraps the Volcengine Ark Image Generation API. It supports text-to-image, image editing, multi-reference fusion, sequential/group generation, PNG output, prompt optimization, web search, and streaming output. Works with Seedream 5.0-lite (default), 4.5, and 4.0 models.

## Quick start

```bash
# Text to image (simplest form)
uv run {baseDir}/scripts/generate_image.py --prompt "一只赛博朋克风格的猫"

# Image editing (with reference image)
uv run {baseDir}/scripts/generate_image.py --prompt "变为水墨画风格" --image "https://example.com/photo.jpg"

# Multi-reference fusion
uv run {baseDir}/scripts/generate_image.py --prompt "融合风格" --image "https://a.jpg" --image "https://b.jpg"

# Group/sequential generation
uv run {baseDir}/scripts/generate_image.py --prompt "四格漫画" --sequential --max-images 4

# List available models
uv run {baseDir}/scripts/generate_image.py --list-models
```

## API key

Set `VOLC_API_KEY` env var or pass `--api-key`. Never hardcode keys in scripts.

```bash
export VOLC_API_KEY="your-key"
# or
--api-key your-key
```

## Models

Default model: `doubao-seedream-5-0-260128` (5.0-lite). Override with `--model`.

### Model comparison

| Feature | 5.0-lite | 4.5 | 4.0 |
|---------|----------|-----|-----|
| Model ID | `doubao-seedream-5-0-260128` | `doubao-seedream-4-5-251128` | `doubao-seedream-4-0-250828` |
| Alias | `doubao-seedream-5-0-lite-260128` | — | — |
| Preset sizes | 2K, 3K, 4K | 2K, 4K | 1K, 2K, 4K |
| Output formats | png, jpeg | jpeg only | jpeg only |
| Prompt optimization | standard | standard | standard, fast |
| Streaming | ✅ | ✅ | ✅ |
| Web search | ✅ (only model) | ❌ | ❌ |
| Rate limit | 500 IPM | 500 IPM | 500 IPM |

### When to choose which model

- **5.0-lite (default)** — Best overall quality. Only model supporting PNG output, 3K resolution, and web search. Use for most tasks.
- **4.5** — High quality, slightly different style. Good alternative to 5.0-lite.
- **4.0** — Supports `--prompt-optimization fast` for quicker results. Good for rapid iteration. Also supports 1K for smaller/faster generation.

## Size and resolution

Two ways to specify size (cannot mix):

**Method 1 — Preset** (recommended for most cases):
```bash
--size 2K    # 2048x2048 (default)
--size 3K    # 3072x3072 (5.0-lite only)
--size 4K    # 4096x4096 (all models)
--size 1K    # 1024x1024 (4.0 only)
```

**Method 2 — Pixel format** (for custom aspect ratios):
```bash
--size 3840x2160    # 16:9 widescreen
--size 1080x1920    # 9:16 portrait
--size 1200x1200    # custom square
```

### Resolution table (preset sizes × aspect ratios)

When using preset sizes, the model picks the best aspect ratio based on your prompt. For precise control, use pixel format.

| Preset | 1:1 | 4:3 | 3:4 | 16:9 | 9:16 | 3:2 | 2:3 | 21:9 |
|--------|-----|-----|-----|------|------|-----|-----|------|
| 1K | 1024×1024 | 1152×864 | 864×1152 | 1280×720 | 720×1280 | 1248×832 | 832×1248 | 1512×648 |
| 2K | 2048×2048 | 2304×1728 | 1728×2304 | 2848×1600 | 1600×2848 | 2496×1664 | 1664×2496 | 3136×1344 |
| 3K | 3072×3072 | 3456×2592 | 2592×3456 | 4096×2304 | 2304×4096 | 3744×2496 | 2496×3744 | 4704×2016 |
| 4K | 4096×4096 | 4704×3520 | 3520×4704 | 5504×3040 | 3040×5504 | 4992×3328 | 3328×4992 | 6240×2656 |

### Pixel format constraints

- **5.0-lite**: total pixels ∈ [3,686,400 ~ 16,777,216], aspect ratio ∈ [1/16 ~ 16]
- **4.5**: total pixels ∈ [3,686,400 ~ 16,777,216], aspect ratio ∈ [1/16 ~ 16]
- **4.0**: total pixels ∈ [921,600 ~ 16,777,216], aspect ratio ∈ [1/16 ~ 16]

Examples:
- ✅ `3840x2160` → 8,294,400 pixels, ratio 1.78 → valid for all models
- ✅ `2160x3840` → same pixels, ratio 0.56 → valid for all models
- ❌ `1500x1500` → 2,250,000 pixels < 3,686,400 minimum → invalid for 5.0-lite/4.5

## Flags reference

### Required

- `--prompt` — Text description for image generation. Supports Chinese and English. Recommended under 300 Chinese characters or 600 English words.

### Model and size

- `--model` — Model ID (default: `doubao-seedream-5-0-260128`)
- `--size` — Preset (`1K`/`2K`/`3K`/`4K`) or pixel (`WIDTHxHEIGHT`, default: `2K`)

### Image input

- `--image` — Reference image URL or base64. Repeat for multiple images (max 14 total). Used for image editing and multi-reference fusion.

Supported input formats: jpeg, png, webp, bmp, tiff, gif, heic, heif.
Constraints: max 30MB per image, max 60MP (width×height), aspect ratio [1/16, 16].

### Output control

- `--output-format` — `jpeg` (default) or `png` (5.0-lite only)
- `--response-format` — `url` (default, 24h valid) or `b64_json` (base64 encoded)
- `--watermark` / `--no-watermark` — Enable/disable "AI生成" watermark (default: enabled)

### Generation mode

- `--sequential` — Enable group/sequential generation (multiple related images)
- `--max-images` — Number of images in sequential mode (1-15, default: 1)
- `--stream` — Enable streaming output (get results as generated)
- `--web-search` — Enable web search for real-time info (**5.0-lite only**). Uses `tools: [{type: "web_search"}]` API parameter.

### Prompt enhancement

- `--prompt-optimization` — `standard` (all models) or `fast` (4.0 only). Rewrites prompt for better results.

### Utilities

- `--list-models` — List available Seedream models and their capabilities
- `--api-key` — Volcengine API key (or set `VOLC_API_KEY` env)

## Use cases with complete examples

### 1. Text to image (basic)

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

### 2. Text to image (with specific size)

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

# Custom widescreen
uv run {baseDir}/scripts/generate_image.py --prompt "赛博朋克城市夜景" --size 3840x2160

# Portrait for phone wallpaper
uv run {baseDir}/scripts/generate_image.py --prompt "极简抽象艺术" --size 1080x1920
```

### 3. Image editing (single reference)

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

### 4. Multi-reference fusion

```bash
# Combine 2 images
uv run {baseDir}/scripts/generate_image.py \
  --prompt "将图1的服装换为图2的服装" \
  --image "https://example.com/person.jpg" \
  --image "https://example.com/clothing.jpg"

# Combine 3+ images
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. Sequential/group generation

```bash
# Generate 4 related images
uv run {baseDir}/scripts/generate_image.py \
  --prompt "生成一组电影级科幻写实风的4张影视分镜" \
  --sequential --max-images 4

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

### 6. PNG output

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

### 7. Prompt optimization

```bash
# Standard mode (higher quality, all models)
uv run {baseDir}/scripts/generate_image.py \
  --prompt "一只猫" \
  --prompt-optimization standard

# Fast mode (quicker, 4.0 only)
uv run {baseDir}/scripts/generate_image.py \
  --prompt "一只猫" \
  --model doubao-seedream-4-0-250828 \
  --prompt-optimization fast
```

### 8. Web search (real-time info, 5.0-lite only)

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

# Current events
uv run {baseDir}/scripts/generate_image.py \
  --prompt "2026年最流行的时尚趋势海报" \
  --web-search
```

### 9. No watermark (commercial use)

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

## Prompt writing tips

- **Language**: Supports Chinese and English. English tends to produce slightly better results for complex scenes, but Chinese works well too.
- **Length**: Under 300 Chinese characters or 600 English words recommended. Too long → model may ignore some details.
- **Specificity**: Be specific. "赛博朋克风格的猫，霓虹灯光，雨夜街道，4K，电影感" > "一只猫"
- **Style keywords**: Append style terms for control:
  - 水墨画风格 (ink painting)
  - 油画风格 (oil painting)
  - 写实摄影 (photorealistic)
  - 扁平化插画 (flat illustration)
  - 电影感 (cinematic)
  - 杂志封面 (magazine cover)
- **Structure**: For complex scenes, describe subject → composition → style → lighting → quality

## Output interpretation

Script stdout contains exactly one of:

- `MEDIA_URL: <url>` — Image download link. **Valid for 24 hours.** Use markdown: `![description](url)`
- `MEDIA_B64: <base64>` — Base64 encoded image data (when `--response-format b64_json`)
- `ERROR: <msg>` — Error occurred. Check message for details.

## Error handling

| Error | Cause | Fix |
|-------|-------|-----|
| `API key required` | No key provided | Set `VOLC_API_KEY` env or pass `--api-key` |
| `API request failed: 401` | Invalid API key | Check key at Volcengine console |
| `API request failed: 429` | Rate limited (500 IPM) | Wait and retry |
| `No image data in response` | API error | Check prompt/params, retry |
| `WARNING: may not support` | Model+size/format mismatch | Check model capabilities table above |

## Workflow

1. Parse user's image request to determine: text-to-image, editing, fusion, or sequential
2. Choose appropriate model (default: 5.0-lite unless specific need)
3. Determine size: use preset for general, pixel format for specific aspect ratio
4. Build and run the command with appropriate flags
5. Parse stdout for `MEDIA_URL:` or `MEDIA_B64:`
6. Display to user as markdown image or file
7. If URL, remind user it expires in 24h if they need to save it

## Input image requirements

- **Formats**: jpeg, png, webp, bmp, tiff, gif, heic, heif
- **Max size**: 30MB per image
- **Max pixels**: 60,000,000 (width × height)
- **Aspect ratio**: [1/16, 16]
- **Min dimension**: > 14px per side
- **Max images**: 14 per request
- **Total**: input images + output images ≤ 15

## Rate limits

All models: 500 images per minute (IPM). Plan batch operations accordingly.

## Full reference

For detailed API parameter docs, see [references/REFERENCE.md](references/REFERENCE.md).