Photo Studio

Generate professional AI-enhanced portraits and group photos using Seedream 4.5 AI model.

Quick Start

# Interactive mode - easiest way to start
python scripts/main.py generate --photo path/to/your/photo.jpg

# Non-interactive mode - for agent integration
python scripts/main.py generate --photo "$USER_PHOTO" --scenario portrait --non-interactive

Core Workflow

1. Select scenario from 9 options: celebrity, portrait, couple, family, edit, fusion, series, poster, free
2. Provide inputs: photos, styles, templates, prompts based on scenario
3. Generate images: CLI preprocesses photos, calls Seedream 4.5 API, saves results to output/images/
4. Review and save: View, reorder, regenerate, or confirm images

Essential Commands

Generate Images

# Celebrity photos with characters
python scripts/main.py generate --photo "$USER_PHOTO" --scenario celebrity --non-interactive

# Portrait photos with style
python scripts/main.py generate --photo "$USER_PHOTO" --scenario portrait --style "职业商务照" --non-interactive

# Couple photos with pose and background
python scripts/main.py generate --photos "$PHOTO1,$PHOTO2" --scenario couple --pose "手牵手面向镜头" --background "海滩日落" --non-interactive

# Family photos with template
python scripts/main.py generate --photos "$PHOTO1,$PHOTO2,$PHOTO3" --scenario family --template "温馨家庭聚会" --non-interactive

# Edit images (change clothing, material, background, style, enhance)
python scripts/main.py generate --photo "$USER_PHOTO" --scenario edit --template change-clothing --clothing "运动外套" --non-interactive

# Fuse images (outfit, person-scenery, brand, multi-person)
python scripts/main.py generate --photos "$PHOTO1,$PHOTO2" --scenario fusion --template outfit-fusion --non-interactive

# Create series (seasons, brand kit, character states, story sequence)
python scripts/main.py generate --photo "$USER_PHOTO" --scenario series --template seasons --count 4 --non-interactive

# Design poster (movie, event, product)
python scripts/main.py generate --photo "$USER_PHOTO" --scenario poster --template movie-poster --non-interactive

# Free mode with custom prompt
python scripts/main.py generate --photo "$USER_PHOTO" --scenario free --prompt "A futuristic cyberpunk portrait" --non-interactive

List Available Options

# List all scenarios
python scripts/main.py list-scenarios

# List styles for portrait/couple/family/celebrity
python scripts/main.py list-styles --scenario <scenario_id>

# List couple poses
python scripts/main.py list-poses

# List family templates
python scripts/main.py list-templates

# List backgrounds for couple/family
python scripts/main.py list-backgrounds --scenario <scenario_id>

# List characters
python scripts/main.py list-characters

Configuration and Utilities

# View configuration
python scripts/main.py config --show

# Update configuration
python scripts/main.py config --set generation.default_image_count=3

# Add custom character
python scripts/main.py add-character "Character Name" "Description" --scene "Scene"

# Clean temporary files
python scripts/main.py cleanup

Scenarios Overview

Environment Setup

# Install dependencies
pip install -r requirements.txt

# Set API key (required for operation)
# API key environment variable name: ARK_API_KEY
# API will return error if key is not properly configured

# Mock mode for testing without API (optional)
export MOCK_API=true

Configuration

Key settings in config.json:

• generation.imagewidth / generation.imageheight - Image dimensions (default: 2048)
• generation.defaultimagecount - Default number of images (default: 5)
• scenarios.default_scenario - Default scenario (default: celebrity)

File Structure

photo-studio-skill/
 ├── SKILL.md                    # This file
 ├── scripts/                    # Executable CLI tools
 │   └── main.py                # Main entry point
 ├── data/                       # Scenario templates and options
 ├── references/                 # Feature documentation
 │   ├── celebrity.md           # Celebrity photos with movie characters
 │   ├── portrait.md            # Professional personal portraits
 │   ├── couple.md               # Couple/friend portraits
 │   ├── family.md               # Family group photos
 │   ├── edit.md                # Image editing
 │   ├── fusion.md              # Multi-photo fusion
 │   ├── series.md              # Series creation
 │   ├── poster.md              # Poster design
 │   └── free.md                # Free mode with custom prompts
 ├── output/images/             # Generated images
 ├── temp/                      # Temporary files
 ├── logs/                      # Error logs
 ├── config.json                # Configuration settings
 ├── requirements.txt           # Python dependencies
 ├── AGENTS.md                  # Agent development guidelines
 └── README.md                  # Project documentation

References

Load these reference files when working with specific features:

Feature Modules:

• [references/celebrity.md](references/celebrity.md) - Celebrity photos with movie characters
• [references/portrait.md](references/portrait.md) - Professional personal portraits with various styles
• [references/couple.md](references/couple.md) - Couple or friend portraits with poses and backgrounds
• [references/family.md](references/family.md) - Family group photos with templates
• [references/edit.md](references/edit.md) - Image editing (clothing, material, background, style, enhancement)
• [references/fusion.md](references/fusion.md) - Multi-photo fusion (outfit, person-scenery, brand, composite)
• [references/series.md](references/series.md) - Series creation (seasons, brand kit, character states, story)
• [references/poster.md](references/poster.md) - Poster design (movie, event, product)
• [references/free.md](references/free.md) - Free mode with custom prompts

Technical Notes

Image Generation

• Model: Seedream 4.5 (doubao-seedream-4.5-251128)
• Resolution: 2048x2048 (configurable)
• Supports 1-14 reference photos
• Uses image-to-image generation with user photos as reference
• Processing time: ~10-20 seconds per image

Multi-Photo Scenarios

• Couple and family scenarios use multi-reference image fusion
• Person count controlled via prompt descriptions (not precise)

Mock Mode Benefits

• No API costs
• Fast testing (500ms instead of 10-20 seconds)
• No network dependency
• Consistent test results

Troubleshooting

Image generation fails:

• Check internet connection
• Verify API key is properly configured (see Environment Setup)
• Ensure photos are clear and well-lit (≥1024×1024 recommended)
• Check logs/ directory for detailed errors

Common issues:

• Large photos require more processing time
• API rate limits may apply
• Person count in group photos is controlled via prompt (not precise)