Seedream CLI

A command-line tool for AI image generation using Seedream through the AceDataCloud API.

Generate AI images directly from your terminal — no MCP client required.

Features

• Image Generation — Generate images from text prompts with multiple models
• Image Editing — Edit, combine, and transform images with AI
• Multiple Models — doubao-seedream-5-0-pro-260628, doubao-seedream-5-0-lite-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828
• Task Management — Query tasks, batch query, wait with polling
• Rich Output — Beautiful terminal tables and panels via Rich
• JSON Mode — Machine-readable output with --json for piping

Quick Start

1. Get API Token

Get your API token from AceDataCloud Platform:

1. Sign up or log in
2. Navigate to the Seedream API page
3. Click "Acquire" to get your token

2. Install

# Install with pip
pip install seedream-cli

# Or with uv (recommended)
uv pip install seedream-cli

# Or from source
git clone https://github.com/AceDataCloud/SeedreamCli.git
cd SeedreamCli
pip install -e .

3. Configure

# Set your API token
export ACEDATACLOUD_API_TOKEN=your_token_here

# Or use .env file
cp .env.example .env
# Edit .env with your token

4. Use

# Generate an image
seedream generate "A test image"

# Edit an image
seedream edit "Make it look like a painting" -i https://example.com/photo.jpg

# Decompose a poster into editable layers
seedream decompose https://example.com/poster.png --resolution 1.5K --json

# Stream Lite image events as NDJSON
seedream generate "A four-panel storyboard" --sequential-image-generation auto \
  --sequential-max-images 4 --stream --json

# Check task status
seedream task <task-id>

# Wait for completion
seedream wait <task-id> --interval 5

# List available models
seedream models

Commands

Global Options

--token TEXT    API token (or set ACEDATACLOUD_API_TOKEN env var)
--version       Show version
--help          Show help message

Most commands support:

--json          Output raw JSON (for piping/scripting)
--model TEXT    Seedream model version (default: doubao-seedream-5-0-lite-260128)

Available Models

Configuration

Environment Variables

Development

Setup Development Environment

git clone https://github.com/AceDataCloud/SeedreamCli.git
cd SeedreamCli
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,test]"

Run Tests

pytest
pytest --cov=seedream_cli
pytest tests/test_integration.py -m integration

Code Quality

ruff format .
ruff check .
mypy seedream_cli

Seedream 5.0 constraints

• Pro supports 1K/1.5K/2K, prompt optimization standard/fast, transparent-background editing, and layer decomposition. It does not support sequential generation, streaming, or web search.
• Lite supports 2K/3K/4K, sequential generation, streaming, web search, and standard prompt optimization. It does not support layer decomposition or transparent-background mode.
• --stream uses AceDataCloud normalized NDJSON and cannot be combined with --async or --callback-url.
• Layer results include z_index, name, description, and absolute/normalized bounding boxes. JSON output preserves every field.

Docker

docker pull ghcr.io/acedatacloud/seedream-cli:latest
docker run --rm -e ACEDATACLOUD_API_TOKEN=your_token \
  ghcr.io/acedatacloud/seedream-cli generate "A test image"

Project Structure

SeedreamCli/
├── seedream_cli/                # Main package
│   ├── __init__.py
│   ├── __main__.py            # python -m seedream_cli entry point
│   ├── main.py                # CLI entry point
│   ├── core/                  # Core modules
│   │   ├── client.py          # HTTP client for Seedream API
│   │   ├── config.py          # Configuration management
│   │   ├── exceptions.py      # Custom exceptions
│   │   └── output.py          # Rich terminal formatting
│   └── commands/              # CLI command groups
│       ├── image.py           # Image generation commands
│       ├── task.py            # Task management commands
│       └── info.py            # Info & utility commands
├── tests/                     # Test suite
├── .github/workflows/         # CI/CD (lint, test, publish to PyPI)
├── Dockerfile                 # Container image
├── deploy/                    # Kubernetes deployment configs
├── .env.example               # Environment template
├── pyproject.toml             # Project configuration
└── README.md

Seedream CLI vs Seedream MCP

Both tools use the same AceDataCloud API and share the same API token.

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing)
5. Open a Pull Request

Development Requirements

• Python 3.10+
• Dependencies: pip install -e ".[all]"
• Lint: ruff check . && ruff format --check .
• Test: pytest

License

This project is licensed under the MIT License — see the LICENSE file for details.