seedream

Seedream Image Generation

Generate high-quality AI images using the Volcano Engine Seedream model, supporting text-to-image (T2I), image editing (I2I), multi-image fusion, image set generation, web search, and other creative modes.

✨ Node.js Version: This script is implemented using Node.js and requires no Python environment. The entry script automatically detects the Node.js runtime (preferring the system node, falling back to the LobsterAI built-in runtime), so both Windows and Mac users can use it out of the box.

Configuration

Base URL: https://ark.cn-beijing.volces.com/api/v3
API Key: Read from the environment variable ARK_API_KEY Read
Authentication Method: Authorization: Bearer {API_KEY}
SDK: Compatible with the Volcano Ark Python SDK

Quick Start

Step 1: Set the API Key

# macOS / Linux - 当前终端临时生效（立即使用）
export ARK_API_KEY="你的API密钥"

# Windows PowerShell - 当前会话临时生效
$env:ARK_API_KEY="你的API密钥"

# 验证设置成功（macOS/Linux）
echo $ARK_API_KEY

# 验证设置成功（Windows）
echo $env:ARK_API_KEY

Step 2: Generate Your First Image

bash "$SKILLS_ROOT/seedream/scripts/generate-image.sh" \
  --prompt "一只可爱的橘色小猫"

How to Configure the API Key

Method 1: Configure via Environment Variables (Recommended)

Set the environment variable in the terminal:

# macOS/Linux
export ARK_API_KEY="你的API密钥"

# 或者添加到 ~/.zshrc 或 ~/.bashrc 以永久生效
echo 'export ARK_API_KEY="你的API密钥"' >> ~/.zshrc
source ~/.zshrc

# Windows PowerShell
$env:ARK_API_KEY="你的API密钥"

# 或者设置系统环境变量以永久生效
[System.Environment]::SetEnvironmentVariable('ARK_API_KEY', '你的API密钥', 'User')

Method 2: Inject at LobsterAI Startup

LobsterAI automatically reads system environment variables, so make sure ARK_API_KEY。

How to Get an API Key:

Visit the Volcano Ark console:https://console.volcengine.com/ark/region:ark+cn-beijing/apikey
Create a new API Key
Copy the key and set it as an environment variable

Prerequisites

No dependencies need to be installed! This script is compatible with Node.js built-in modules.

LobsterAI already includes the Node.js runtime, and all necessary dependencies have been automatically bundled. Windows and Mac users need no additional configuration.

Workflow

Seedream image generation usessynchronous mode, making the process simple and efficient:

Submit Request - Call the API to submit an image generation request
Wait for Generation - The API processes and generates the image directly (usually 30-60 seconds)
Download Image - Download the generated image file from the returned URL

Compared with asynchronous mode, synchronous mode is simpler and more direct, with no need to poll task status.

Quotas and Limits

Free Quota

All Seedream models offer a free quota; for details, please refer to the Volcano Ark console.

Rate Limits

IPM (Images Per Minute): 500 images/minute (Seedream 4.5, 4.0)
Rate limits vary by model; please refer to the official documentation

Image Retention Time

⚠️ Important Reminder：

Task data (including image URLs) is retained for only 24 hours
and will be automatically cleared after the timeout
Be sure to download and save generated images promptly

Usage Examples

Path Note: The examples below use the $SKILLS_ROOT environment variable to reference the script path. LobsterAI automatically sets this variable to point to the actual SKILLs directory location, so there is no need to manually modify the path.

1. Text-to-Image (T2I)

Generate images from text descriptions, suitable for creative inspiration and concept design.

bash "$SKILLS_ROOT/seedream/scripts/generate-image.sh" \
  --prompt "充满活力的特写编辑肖像，模特眼神犀利，头戴雕塑感帽子，色彩拼接丰富，景深较浅，Vogue杂志封面美学风格" \
  --output portrait.png

Example prompts:

"Realistic style, under a clear blue sky, a large field of white daisies, the camera gradually zooms in, finally freezing on a close-up of a single daisy"
"Cartoon style, an orange kitten sitting on a windowsill, sunlight falling on it, a warm and healing atmosphere"
"Cyberpunk style, futuristic city night scene, flickering neon lights, towering skyscrapers"

2. Image editing (I2I) - single image input

Edit an image based on an existing image combined with text instructions.Supports local images and web URLs。

# 使用本地图片
bash "$SKILLS_ROOT/seedream/scripts/generate-image.sh" \
  --prompt "保持模特姿势不变，将服装材质改为透明玻璃质感" \
  --image "/Users/yourname/Pictures/model.jpg" \
  --output edited_model.png

# 使用网络图片
bash "$SKILLS_ROOT/seedream/scripts/generate-image.sh" \
  --prompt "将背景改为海边日落场景" \
  --image "https://example.com/photo.jpg" \
  --output beach_sunset.png

Supported image sources:

✅ Local file:/path/to/image.jpg
✅ Web URL:https://example.com/image.jpg
✅ file:// protocol:file:///path/to/image.jpg

Supported image formats:

jpg, jpeg, png, gif, webp, bmp, tiff, heic

3. Multi-image fusion (multiple image input, single image output)

Fuse features from multiple reference images to generate a new image.Supports mixed use of local images and web images。

bash "$SKILLS_ROOT/seedream/scripts/generate-image.sh" \
  --prompt "将图1的服装换为图2的服装" \
  --image "/Users/yourname/Pictures/person.jpg" \
  --image "https://example.com/clothes.jpg" \
  --output fusion_result.png

Common use cases:

Clothing try-on: person image + clothing image → outfit effect image
Style transfer: photo + style reference image → stylized work
Scene fusion: person + background → composite scene

4. Image set generation (multiple image output)

Generate a set of related images, suitable for comic panels, brand visuals, etc.

Text-to-image set

bash "$SKILLS_ROOT/seedream/scripts/generate-image.sh" \
  --prompt "生成一组共4张连贯插画，核心为同一庭院一角的四季变迁，以统一风格展现四季独特色彩、元素与氛围" \
  --sequential \
  --max-images 4 \
  --output seasons.png

Output files are automatically numbered:seasons_1.png, seasons_2.png, seasons_3.png, seasons_4.png

Single image to image set

bash "$SKILLS_ROOT/seedream/scripts/generate-image.sh" \
  --prompt "参考这个LOGO，做一套户外运动品牌视觉设计，品牌名称为'GREEN'，包括包装袋、帽子、卡片、挂绳等" \
  --image "/Users/yourname/Pictures/logo.png" \
  --sequential \
  --max-images 4 \
  --output brand_design.png

5. Web search enhanced generation (Seedream 5.0 lite)

Enable real-time web search to incorporate the latest online information.

bash "$SKILLS_ROOT/seedream/scripts/generate-image.sh" \
  --prompt "搜索下近期热门的白鸭子单手拿着风车形象，以极具冲击力的视角，设计成巨型装置" \
  --search \
  --output search_result.png

Note：

The web search feature is only available for the Seedream 5.0 lite model
Using --search parameter will automatically switch to the 5.0 lite model
Suitable for creative scenarios that need to incorporate real-time information

Parameter description

Required parameters

Parameter	Description	Example
`--prompt`	Image description prompt (required)	"A cute little cat"

Optional parameters

Parameter	Description	Default value	Optional values
`--image`	Reference image path or URL (can be used multiple times)	None	Local file path or URL
`--model`	Model ID	`doubao-seedream-4-5-251128`	See model list
`--size`	Image size	`2K`	`1K`, `2K`, `4K`
`--no-watermark`	Do not add watermark	No	Flag parameter
`--sequential`	Generate image set	No	Flag parameter
`--max-images`	Number of images in the set	4	1-8
`--search`	Enable web search	No	Flag parameter
`--output`	Output file path	`generated_image.png`	File path
`--poll-interval`	Status query interval (seconds)	5	1-10
`--timeout`	Maximum wait time (seconds)	300	60-600

Model selection

Choose an appropriate model to balance quality, speed, and cost:

Seedream 4.5 (recommended)

Model ID: doubao-seedream-4-5-251128
Features: Latest version, best overall quality
Supports: text-to-image, image-to-image, multi-image fusion, image set generation
Output: 1K-4K resolution options
Rate limit: IPM 500

Seedream 4.0

Model ID: doubao-seedream-4-0-250828
Features: Mature and stable version
Supports: Text-to-image, image-to-image, multi-image fusion, image set generation
Output: 1K-4K resolution options available
Rate limit: IPM 500

Seedream 5.0 lite (dedicated for web search)

Model ID: doubao-seedream-5-0-260128
Features: Supports web search, integrates real-time web information
Usage: Automatically enabled via the --search parameter
Note: API officially opens after 18:00 on February 24, 2026

Recommended use cases:

Pursuing highest quality → 4.5
Stable production environment → 4.0
Need real-time information → 5.0 lite (using --search）

Advanced options

Custom image size

Choose the appropriate size based on your use case:

# 小尺寸（快速预览）
--size "1K"

# 标准尺寸（推荐）
--size "2K"

# 高清晰度
--size "4K"

Note:

The larger the size, the longer the generation time
4K images may take 40-60 seconds

Remove watermark

Generate watermarked-free images (for commercial use):

--no-watermark

Polling and timeout control

Adjust the polling strategy to suit different scenarios:

# 快速查询（适合小图）
--poll-interval 3 --timeout 180

# 标准配置
--poll-interval 5 --timeout 300

# 耐心等待（适合4K或组图）
--poll-interval 10 --timeout 600

Status description

Task statuses that may occur during generation:

Status	Description	Action
`queued`	Task queued	Keep waiting
`running`	Generating image	Keep waiting
`succeeded`	Generation successful	Download image
`failed`	Generation failed	View error information

Error handling

Common errors and solutions

Error: Environment variable ARK_API_KEY not set

Cause: API Key not configured
Solution: Configure according to the instructions in the "How to configure API Key" section

Error: Task creation failed (HTTP 401)

Cause: API Key is invalid or expired
Solution: Check whether the API Key is correct, or regenerate it in the console

Error: Task creation failed (HTTP 400)

Cause: Parameter error (e.g., unsupported size, empty prompt, etc.)
Solution: Check whether the parameters meet the requirements

Error: Task timeout

Cause: Generation time too long or API busy
Solution: Increase the --timeout value, or retry later

Error: Task failed

Cause: Content violation, unclear prompt, image format error, etc.
Solution: Check the prompt content and ensure the image URL is accessible

Error: Rate limit (HTTP 429)

Cause: IPM limit exceeded
Solution: Wait 1 minute and retry, or upgrade your quota

Error: Image file does not exist

Cause: Incorrect local image path
Solution: Check whether the file path is correct and use an absolute path

Output format

The generated images have the following characteristics:

Format: PNG, JPEG (automatically detected based on the output parameter)
Resolution: 1K / 2K / 4K (based on the size parameter)
File size: About 0.5-10 MB (depending on size and complexity)
Naming Rules:
- Single image: the specified filename
- Image group:文件名_1.png, 文件名_2.png, ...

Prompt Best Practices

Characteristics of a Good Prompt

Clear subject description - Describe the main content of the image
Specific style specification - Realistic, cartoon, cyberpunk, etc.
Detail supplementation - Color, lighting, atmosphere, etc.
Composition description - Close-up, panorama, top-down, and other perspectives

Prompt Template

[风格]，[主体描述]，[细节补充]，[构图/氛围]

Example:

写实风格，一只橘色小猫坐在木制窗台上，阳光从左侧洒进来，温暖治愈的氛围，特写构图

Prompt Precautions

✅ Specific description: "A kitten chasing a butterfly" instead of "A kitten playing"
✅ Style specification: "Cyberpunk style" instead of "Nice-looking"
✅ Rich details: "An orange long-haired kitten with blue eyes" instead of "A cat"
❌ Avoid vagueness: overly abstract descriptions will increase randomness
❌ Avoid excessive length: keeping it within 200 characters works best
❌ Avoid violations: do not include violent, pornographic, or other violating content

Common Use Cases

Product Design

bash "$SKILLS_ROOT/seedream/scripts/generate-image.sh" \
  --prompt "现代简约风格，智能手表产品展示，白色背景，工作室灯光" \
  --size "4K"

Artistic Creation

bash "$SKILLS_ROOT/seedream/scripts/generate-image.sh" \
  --prompt "超现实主义，漂浮的岛屿，瀑布从天而降，梦幻色彩" \
  --size "2K"

Social Media Content

bash "$SKILLS_ROOT/seedream/scripts/generate-image.sh" \
  --prompt "美食特写，热气腾腾的拉面，筷子夹起面条，暖色调" \
  --size "2K"

Brand Visual Design

bash "$SKILLS_ROOT/seedream/scripts/generate-image.sh" \
  --prompt "参考logo，生成一套完整的品牌视觉系统，包括名片、海报、包装设计" \
  --image brand_logo.png \
  --sequential \
  --max-images 4

Reference Materials

API Reference:https://www.volcengine.com/docs/82379/1541523
Console:https://console.volcengine.com/ark
API Key Management:https://console.volcengine.com/ark/region:ark+cn-beijing/apikey
Model List:https://www.volcengine.com/docs/82379/1330310

Technical Support

If you encounter problems, you can:

Check the error information output by the script
Check whether the API Key configuration is correct
Visit the Volcano Ark console to view task details
Refer to the official website documentation for more details