Seedream Image Generation

Generate high-quality AI images using the Volcengine Seedream model, supporting multiple creation modes including text-to-image (T2I), image editing (I2I), multi-image fusion, sequential image generation, and web-search-based generation.

✨ Node.js Version: This script is implemented with Node.js, no Python environment required. The entry script automatically detects the Node.js runtime (prioritizes system node, falls back to LobsterAI's built-in runtime), allowing Windows and Mac users to use it out of the box.

Configuration

Base URL:

https://ark.cn-beijing.volces.com/api/v3

API Key: Read from environment variable
```
ARK_API_KEY
```
Authentication:
```
Authorization: Bearer {API_KEY}
```
SDK: Compatible with Volcengine Ark Python SDK

Quick Start

Step 1: Set API Key

bash

# macOS / Linux - Temporary effect in current terminal (use immediately)
export ARK_API_KEY="Your API Key"

# Windows PowerShell - Temporary effect in current session
$env:ARK_API_KEY="Your API Key"

# Verify successful setup (macOS/Linux)
echo $ARK_API_KEY

# Verify successful setup (Windows)
echo $env:ARK_API_KEY

Step 2: Generate Your First Image

bash

bash "$SKILLS_ROOT/seedream/scripts/generate-image.sh" \
  --prompt "A cute orange kitten"

How to Configure API Key

Method 1: Configure via Environment Variables (Recommended)

Set the environment variable in the terminal:

bash

# macOS/Linux
export ARK_API_KEY="Your API Key"

# Or add to ~/.zshrc or ~/.bashrc for permanent effect
echo 'export ARK_API_KEY="Your API Key"' >> ~/.zshrc
source ~/.zshrc

powershell

# Windows PowerShell
$env:ARK_API_KEY="Your API Key"

# Or set system environment variable for permanent effect
[System.Environment]::SetEnvironmentVariable('ARK_API_KEY', 'Your API Key', 'User')

Method 2: Inject When Starting LobsterAI

LobsterAI automatically reads system environment variables. Ensure

ARK_API_KEY

is set before starting LobsterAI.

How to Obtain API Key:

Visit Volcengine 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

Pre-check

No dependencies required! This script is compatible with Node.js built-in modules.

LobsterAI includes the Node.js runtime, and all necessary dependencies are automatically packaged. Windows and Mac users do not need additional configuration.

Workflow

Seedream image generation uses synchronous mode, with a simple and efficient process:

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

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

Quotas and Limits

Free Tier

All Seedream models offer free quotas. Please refer to the Volcengine Ark Console for details.

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 Note:

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

Usage Examples

Path Explanation: 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 modify the path manually.

1. Text-to-Image (T2I)

Generate images based on text descriptions, suitable for creative inspiration and conceptual design.

bash

bash "$SKILLS_ROOT/seedream/scripts/generate-image.sh" \
  --prompt "Dynamic close-up editorial portrait with a model having sharp eyes, wearing a sculptural hat, rich color blocking, shallow depth of field, Vogue magazine cover aesthetic" \
  --output portrait.png

Example Prompts:

"Realistic style, under a clear blue sky, a large field of white daisies, the camera gradually zooms in, finally focusing on a close-up of a single daisy"
"Cartoon style, an orange kitten sitting on a windowsill, sunlight shining on it, warm and healing atmosphere"
"Cyberpunk style, future city night scene, neon lights flickering, tall buildings lining the streets"

2. Image Editing (I2I) - Single Image Input

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

bash

# Use local image
bash "$SKILLS_ROOT/seedream/scripts/generate-image.sh" \
  --prompt "Keep the model's pose unchanged, change the clothing material to transparent glass texture" \
  --image "/Users/yourname/Pictures/model.jpg" \
  --output edited_model.png

# Use web image
bash "$SKILLS_ROOT/seedream/scripts/generate-image.sh" \
  --prompt "Change the background to a seaside sunset scene" \
  --image "https://example.com/photo.jpg" \
  --output beach_sunset.png

Supported Image Sources:

✅ Local files:
```
/path/to/image.jpg
```
✅ Web URLs:
```
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 Inputs, Single Output)

Generate new images by fusing features from multiple reference images. Supports mixing local and web images.

bash

bash "$SKILLS_ROOT/seedream/scripts/generate-image.sh" \
  --prompt "Change the clothing in image 1 to the clothing in image 2" \
  --image "/Users/yourname/Pictures/person.jpg" \
  --image "https://example.com/clothes.jpg" \
  --output fusion_result.png

Common Use Cases:

Virtual try-on: Person image + clothing image → Outfit preview
Style transfer: Photo + style reference image → Styled work
Scene fusion: Person + background → Composite scene

4. Sequential Image Generation (Multiple Outputs)

Generate a set of content-related images, suitable for comic storyboards, brand visuals, etc.

Text-to-Sequential Images

bash

bash "$SKILLS_ROOT/seedream/scripts/generate-image.sh" \
  --prompt "Generate a set of 4 coherent illustrations focusing on the four seasons' changes in a corner of the same courtyard, showcasing the unique colors, elements, and atmosphere of each season in a unified style" \
  --sequential \
  --max-images 4 \
  --output seasons.png

Output files will be automatically numbered:

seasons_1.png

seasons_2.png

seasons_3.png

seasons_4.png

Single Image-to-Sequential Images

bash

bash "$SKILLS_ROOT/seedream/scripts/generate-image.sh" \
  --prompt "Refer to this LOGO to create a set of outdoor sports brand visual designs, with the brand name 'GREEN', including packaging bags, hats, cards, lanyards, etc." \
  --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 integrate the latest online information.

bash

bash "$SKILLS_ROOT/seedream/scripts/generate-image.sh" \
  --prompt "Search for the recently popular image of a white duck holding a windmill with one hand, design it into a giant installation from a highly impactful perspective" \
  --search \
  --output search_result.png

Notes:

Web search functionality is only available for the Seedream 5.0 lite model
Using the
```
--search
```
parameter will automatically switch to the 5.0 lite model
Suitable for creation scenarios that require integrating real-time information

Parameter Description

Required Parameters

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

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 resolution	`2K`	`1K` , `2K` , `4K`
`--no-watermark`	Do not add watermark	No	Flag parameter
`--sequential`	Generate sequential images	No	Flag parameter
`--max-images`	Number of sequential images	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 waiting time (seconds)	300	60-600

Model Selection

Choose the 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
Supported Functions: Text-to-image, image-to-image, multi-image fusion, sequential image generation
Output: 1K-4K resolution optional
Rate Limit: IPM 500

Seedream 4.0

Model ID:
```
doubao-seedream-4-0-250828
```
Features: Mature and stable version
Supported Functions: Text-to-image, image-to-image, multi-image fusion, sequential image generation
Output: 1K-4K resolution optional
Rate Limit: IPM 500

Seedream 5.0 lite (For Web Search Only)

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

Recommended Use Scenarios:

Pursue highest quality → 4.5
Stable production environment → 4.0
Need real-time information → 5.0 lite (use
```
--search
```
)

Advanced Options

Custom Image Resolution

Choose the appropriate resolution based on usage scenarios:

bash

# Small size (quick preview)
--size "1K"

# Standard size (recommended)
--size "2K"

# High definition
--size "4K"

Notes:

Larger resolution results in longer generation time
4K images may take 40-60 seconds

Remove Watermark

Generate watermark-free images (for commercial use):

bash

--no-watermark

Polling and Timeout Control

Adjust polling strategy to suit different scenarios:

bash

# Fast query (suitable for small images)
--poll-interval 3 --timeout 180

# Standard configuration
--poll-interval 5 --timeout 300

# Wait patiently (suitable for 4K or sequential images)
--poll-interval 10 --timeout 600

Status Description

Possible task statuses during generation:

Status	Description	Action
`queued`	Task is queued	Continue waiting
`running`	Image is being generated	Continue waiting
`succeeded`	Generation succeeded	Download image
`failed`	Generation failed	Check error message

Error Handling

Common Errors and Solutions

Error: Environment variable ARK_API_KEY not set

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

Error: Task creation failed (HTTP 401)

Cause: Invalid or expired API Key
Solution: Check if 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 if parameters meet requirements

Error: Task timeout

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

Error: Task failed

Cause: Violent content, unclear prompt, incorrect image format, etc.
Solution: Check prompt content, ensure image URL is accessible

Error: Rate limit exceeded (HTTP 429)

Cause: Exceeded IPM limit
Solution: Wait 1 minute and try again, or upgrade quota

Error: Image file does not exist

Cause: Incorrect local image path
Solution: Check if the file path is correct, use absolute path

Output Format

Generated images have the following characteristics:

Format: PNG, JPEG (automatically detected based on output parameter)
Resolution: 1K / 2K / 4K (based on size parameter)
File Size: Approximately 0.5-10 MB (depends on resolution and complexity)
Naming Rules:
- Single image: Specified file name
- Sequential images:
```
filename_1.png
```
  ,
```
filename_2.png
```
  , ...

Prompt Best Practices

Characteristics of Excellent Prompts

Clear Subject Description - Explain the main content of the image
Specific Style Specification - Realistic, cartoon, cyberpunk, etc.
Detail Supplements - Colors, lighting, atmosphere, etc.
Composition Instructions - Close-up, panoramic, bird's-eye view, etc.

Prompt Template

[Style], [Subject Description], [Detail Supplements], [Composition/Atmosphere]

Example:

Realistic style, an orange kitten sitting on a wooden windowsill, sunlight shining from the left, warm and healing atmosphere, close-up composition

Prompt Notes

✅ Specific description: "Kitten chasing a butterfly" instead of "Kitten playing"
✅ Style explanation: "Cyberpunk style" instead of "Nice-looking"
✅ Rich details: "Orange long-haired kitten with blue eyes" instead of "Cat"
❌ Avoid ambiguity: Too abstract descriptions increase randomness
❌ Avoid excessive length: Best to keep within 200 words
❌ Avoid violations: Do not include violent, pornographic, or other prohibited content

Common Use Scenarios

Product Design

bash

bash "$SKILLS_ROOT/seedream/scripts/generate-image.sh" \
  --prompt "Modern minimalist style, smartwatch product display, white background, studio lighting" \
  --size "4K"

Art Creation

bash

bash "$SKILLS_ROOT/seedream/scripts/generate-image.sh" \
  --prompt "Surrealism, floating islands, waterfalls falling from the sky, dreamy colors" \
  --size "2K"

Social Media Content

bash

bash "$SKILLS_ROOT/seedream/scripts/generate-image.sh" \
  --prompt "Food close-up, steaming ramen, chopsticks picking up noodles, warm color tones" \
  --size "2K"

Brand Visual Design

bash

bash "$SKILLS_ROOT/seedream/scripts/generate-image.sh" \
  --prompt "Refer to the logo to generate a complete brand visual system, including business cards, posters, packaging designs" \
  --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 messages output by the script
Verify that the API Key configuration is correct
Visit the Volcengine Ark Console to view task details
Refer to the official website documentation for more details

seedream

NPX Install

Tags

SKILL.md Content (Chinese)

Seedream Image Generation

Configuration

Quick Start

How to Configure API Key

Pre-check

Workflow

Quotas and Limits

Free Tier

Rate Limits

Image Retention Time

Usage Examples

1. Text-to-Image (T2I)

2. Image Editing (I2I) - Single Image Input

3. Multi-Image Fusion (Multiple Inputs, Single Output)

4. Sequential Image Generation (Multiple Outputs)

Text-to-Sequential Images

Single Image-to-Sequential Images

5. Web-Search Enhanced Generation (Seedream 5.0 lite)

Parameter Description

Required Parameters

Optional Parameters

Model Selection

Seedream 4.5 (Recommended)

Seedream 4.0

Seedream 5.0 lite (For Web Search Only)

Advanced Options

Custom Image Resolution

Remove Watermark

Polling and Timeout Control

Status Description

Error Handling

Common Errors and Solutions

Output Format

Prompt Best Practices

Characteristics of Excellent Prompts

Prompt Template

Prompt Notes

Common Use Scenarios

Product Design

Art Creation

Social Media Content

Brand Visual Design

Reference Materials

Technical Support