byted-seedream-image-generate

What this skill does

# byted-seedream-image-generate

## Description

Generate high-quality images from text prompts using Volcano Engine Seedream models. This skill provides access to three powerful Seedream model versions (4.0, 4.5, and 5.0-lite), each offering unique capabilities for different use cases.

## When to Use This Skill

Use this skill when:
- Users want to create images from text descriptions
- Users need to generate artwork in various artistic styles
- Users want to create visual content for creative projects
- Users need AI-powered image generation capabilities
- Users want to convert reference images to different styles
- Users need to generate multiple images in batch
- Users require high-quality, professional-looking images

## Model Versions

| Version | Model Name | Release Date | Recommendation | Best For |
|---------|------------|--------------|----------------|----------|
| 4.0 | doubao-seedream-4-0-250828 | August 2025 | ⭐⭐⭐ | Daily use, quick generation |
| 4.5 | doubao-seedream-4-5-251128 | November 2025 | ⭐⭐⭐⭐ | Detail-oriented work, complex scenes |
| 5.0 | doubao-seedream-5-0-260128 | 2026 | ⭐⭐⭐⭐⭐ | Highest quality, best creativity, tools support |

## Features

- **Text-to-Image**: Generate images from detailed text descriptions
- **Image-to-Image**: Transform reference images into different styles
- **Batch Generation**: Create multiple images in a single request
- **Multiple Versions**: Choose from 4.0, 4.5, or 5.0-lite models
- **Watermark Control**: Option to disable watermarks
- **Custom Sizes**: Support for various image dimensions
- **Output Formats**: PNG and JPEG formats (5.0-lite only)
- **Web Search Tools**: Internet search integration (5.0-lite only)

## Installation & Setup

### Prerequisites

```bash
# Required: API Key configuration
export MODEL_IMAGE_API_KEY="your-api-key-here"
# or
export MODEL_AGENT_API_KEY="your-api-key-here"
# or
export ARK_API_KEY="your-api-key-here"

# Optional: API Base URL (default already configured)
export MODEL_IMAGE_API_BASE="https://ark.cn-beijing.volces.com/api/v3"
# or
export ARK_BASE_URL="https://ark.cn-beijing.volces.com/api/v3"
```

The script will prioritize:
1. Environment variables (`ARK_API_KEY`, `MODEL_IMAGE_API_KEY`, `MODEL_AGENT_API_KEY`)
2. Environment variables (`ARK_BASE_URL`, `MODEL_IMAGE_API_BASE`)
3. Default values

## Usage

### Basic Usage (5.0-lite version recommended)

```bash
cd scripts
python seedream_image_generate.py -p "A cute kitten playing in a garden"
```

### Specify Version

```bash
# Use 4.0 version
python seedream_image_generate.py -p "A cute kitten" --version 4.0

# Use 4.5 version
python seedream_image_generate.py -p "A cute kitten" --version 4.5

# Use 5.0-lite version (recommended)
python seedream_image_generate.py -p "A cute kitten" --version 5.0
```

### Advanced Options

```bash
# Custom size without watermark
python seedream_image_generate.py -p "Beautiful sunset" -s 2048x2048 --no-watermark --version 5.0

# Batch generation
python seedream_image_generate.py -p "Generate 3 cute dog pictures" -g --max-images 3 --version 4.5

# Image-to-image
python seedream_image_generate.py -p "Convert this image to anime style" -i "https://example.com/image.jpg" --version 5.0

# Web search tool (5.0-lite only)
python seedream_image_generate.py -p "Latest 2026 smartphone" --web-search --version 5.0

# Custom output format (5.0-lite only)
python seedream_image_generate.py -p "A beautiful landscape" --output-format png --version 5.0

# List all supported versions
python seedream_image_generate.py --list-versions
```

## Command Line Options

| Option | Shortcut | Description | Default |
|--------|----------|-------------|---------|
| `--prompt` | `-p` | Image description text (required) | - |
| `--version` | `-v` | Version selection: `4.0`, `4.5`, `5.0` | `5.0` |
| `--size` | `-s` | Image dimensions | `2048x2048` |
| `--image` | `-i` | Single reference image URL | - |
| `--images` | - | Multiple reference image URLs (space separated) | - |
| `--group` | `-g` | Enable batch image generation | `false` |
| `--max-images` | - | Maximum images for batch generation | `15` |
| `--output-format` | - | Output format: `png` or `jpeg` (5.0 only) | `jpeg` |
| `--response-format` | - | Response format: `url` or `b64_json` | `url` |
| `--stream` | - | Enable streaming output | `false` |
| `--web-search` | - | Enable web search tool (5.0 only) | `false` |
| `--optimize-prompt-mode` | - | Prompt optimization mode: `standard` or `fast` | - |
| `--timeout` | `-t` | Timeout in seconds | `1200` |
| `--no-watermark` | - | Disable watermark | `false` |
| `--list-versions` | - | List all supported versions | - |

## Python API Usage

```python
import asyncio
import sys

sys.path.append("scripts")
from seedream_image_generate import seedream_generate

async def main():
    # Use 5.0-lite version (default)
    result = await seedream_generate([
        {
            "prompt": "A cute kitten",
            "size": "2048x2048",
            "watermark": False,
            "output_format": "png"  # 5.0-lite only
        }
    ], version="5.0")
    
    print(result)

asyncio.run(main())
```

## Version Selection Guide

### Choose 4.0 if:
- You need quick daily generation
- Quality requirements are not extremely high
- You need faster generation speed
- Simple scenes and styles

### Choose 4.5 if:
- You want richer details
- You're working with complex scenes
- You need better style reproduction
- You have moderate quality requirements

### Choose 5.0-lite (Recommended) if:
- You want the highest quality
- You need breakthrough creative expression
- You have extreme detail requirements
- **You need tools parameter (like web search)** ⭐
- **You need custom output format (png/jpeg)** ⭐
- Important projects and work

**When in doubt, use 5.0-lite!** ⭐

## Prompt Engineering Tips

### Basic Prompt Structure
```
[Subject Description] + [Style/Art Movement] + [Lighting/Atmosphere] + [Quality/Resolution]
```

### Advanced Prompts (Optimized for 5.0-lite)
```
[Subject Description], [Creative Style/Art Movement], [Unique Perspective/Composition], [Special Lighting/Atmosphere], [Emphasizing 5.0-lite creative expression]
```

## Parameter Support by Version

| Parameter | Seedream 4.0 | Seedream 4.5 | Seedream 5.0-lite | Description |
|-----------|--------------|--------------|-------------------|-------------|
| model | ✅ | ✅ | ✅ | Model name |
| prompt | ✅ | ✅ | ✅ | Prompt (required) |
| image | ✅ | ✅ | ✅ | Reference image(s) |
| size | ✅ | ✅ | ✅ | Image dimensions |
| sequential_image_generation | ✅ | ✅ | ✅ | Batch generation control |
| sequential_image_generation_options | ✅ | ✅ | ✅ | Batch generation config |
| response_format | ✅ | ✅ | ✅ | Response format (url/b64_json) |
| watermark | ✅ | ✅ | ✅ | Watermark (true/false) |
| stream | ✅ | ✅ | ✅ | Streaming output |
| optimize_prompt_options | ✅ | ✅ | ✅ | Prompt optimization config |
| **tools** | ❌ | ❌ | **✅** | Tool configuration (5.0-lite only) |
| **output_format** | ❌ | ❌ | **✅** | Output format (png/jpeg, 5.0-lite only) |


## Final Return Info

### For OpenClaw
1. **First, save/download the generated image to an allowed directory**:
   - Recommended: `~/.openclaw/workspace/`

2. **Use the `message tool` to send the image** with these parameters:
   ```json
   {
     "action": "send",
     "message": "Optional text description",
     "media": "/root/.openclaw/workspace/generated-image.jpg"
   }
   ```
   - The tool will automatically: read the local file, upload to the channel server as a web URL, and send as an image message

3. **Verify success**: Check that the tool returns `{"ok": true}` to confirm the image was sent successfully

4. **Normal Text** not message tool: After generation, show list of images with Markdown format, for example：
      ![generated-image-1](https://example.com/image1.png)
    **Very important**:
    The image URL must be an **original online resource link** starting with `https://`, **not** a local image address you have