From e6bf85ca8aba803c4f332af703c19f85c83f2c2d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sebastian=20Kr=C3=BCger?= <valknar@pivoine.art>
Date: Wed, 8 Apr 2026 10:59:29 +0200
Subject: [PATCH] docs: add comprehensive README and .claude to .gitignore

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .gitignore |   1 +
 README.md  | 477 ++++++++++++++++++++++++++++++++++++++++++++++++++---
 2 files changed, 453 insertions(+), 25 deletions(-)

diff --git a/.gitignore b/.gitignore
index dcf9030..1cf31ac 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,4 +1,5 @@
 .venv/
+.claude/
 __pycache__/
 *.pyc
 *.pyo
diff --git a/README.md b/README.md
index 5634724..af923f0 100644
--- a/README.md
+++ b/README.md
@@ -1,52 +1,479 @@
 # Freepik AI CLI
 
-A sophisticated, beautiful Python CLI for generating and manipulating images and video with the [Freepik API](https://docs.freepik.com/introduction).
+A sophisticated, beautiful command-line interface for the [Freepik AI API](https://docs.freepik.com/introduction) — generate images, animate videos, upscale media, and more, all from your terminal.
+
+```
+ ███████╗██████╗ ███████╗███████╗██████╗ ██╗██╗  ██╗
+ ██╔════╝██╔══██╗██╔════╝██╔════╝██╔══██╗██║██║ ██╔╝
+ █████╗  ██████╔╝█████╗  █████╗  ██████╔╝██║█████╔╝
+ ██╔══╝  ██╔══██╗██╔══╝  ██╔══╝  ██╔═══╝ ██║██╔═██╗
+ ██║     ██║  ██║███████╗███████╗██║     ██║██║  ██╗
+ ╚═╝     ╚═╝  ╚═╝╚══════╝╚══════╝╚═╝     ╚═╝╚═╝  ╚═╝
+             AI Media Generation CLI  •  v0.1.0
+```
+
+## Features
+
+- **9 commands** covering image generation, video generation, upscaling, editing, and analysis
+- **Beautiful terminal UI** — live polling panels, progress bars, color-coded status, Rich-themed output
+- **15+ AI models** — Flux, Mystic, Seedream, Kling, Minimax, Runway, and more
+- **Async-first** — all long-running tasks poll with exponential backoff; use `--no-wait` for fire-and-forget
+- **Zero config required** — just set `FREEPIK_API_KEY` and go
 
 ## Installation
 
+### Prerequisites
+
+- Python 3.11+
+- A [Freepik API key](https://www.freepik.com/api) (free tier includes $5 credit)
+
+### Setup
+
 ```bash
+git clone <repo>
+cd freepik
+
 python3 -m venv .venv
-source .venv/bin/activate
+source .venv/bin/activate      # Windows: .venv\Scripts\activate
+
 pip install -e .
 ```
 
+### API Key
+
+```bash
+export FREEPIK_API_KEY=your_api_key_here
+```
+
+Or add it to a `.env` file in the project root (see `.env.example`).
+
 ## Quick Start
 
 ```bash
-export FREEPIK_API_KEY=your_api_key_here
-
 # Generate an image
-freepik generate-image "a majestic mountain at sunset" --model flux-2-pro
+freepik generate-image "a misty forest at dawn, cinematic lighting"
 
-# Generate a video from an image
-freepik generate-video photo.jpg --prompt "gentle ocean waves" --model kling-o1-pro
+# Animate an image into a video
+freepik generate-video photo.jpg --prompt "gentle camera drift" --duration 5
 
-# Upscale an image
+# Upscale an image 4x
 freepik upscale-image photo.jpg --mode precision-v2 --scale 4x
 
 # Upscale a video
-freepik upscale-video clip.mp4 --mode standard
+freepik upscale-video clip.mp4 --mode turbo
+
+# Describe an image (reverse-engineer its prompt)
+freepik describe-image painting.jpg
 ```
 
 ## Commands
 
-| Command | Description |
-|---------|-------------|
-| `generate-image` | Generate images from text prompts |
-| `generate-video` | Animate an image into a video |
-| `generate-icon` | Generate icons in various styles |
-| `upscale-image` | Upscale and enhance images |
-| `upscale-video` | Upscale video to higher resolution |
-| `expand-image` | Outpaint / expand image borders |
-| `relight` | Relight an image (Premium) |
-| `style-transfer` | Apply artistic styles (Premium) |
-| `describe-image` | Reverse-engineer an image into a prompt |
-| `config` | Manage CLI configuration |
+### `generate-image`
+
+Generate an image from a text prompt.
+
+```bash
+freepik generate-image <prompt> [OPTIONS]
+```
+
+| Option | Short | Default | Description |
+|--------|-------|---------|-------------|
+| `--model` | `-m` | `flux-2-pro` | AI model to use |
+| `--aspect-ratio` | `-a` | — | e.g. `16:9`, `1:1`, `9:16`, `4:3` |
+| `--negative-prompt` | `-n` | — | Concepts to exclude |
+| `--seed` | | — | Integer seed for reproducibility |
+| `--input-image` | `-i` | — | Reference image for img2img (flux-kontext-pro) |
+| `--output` | `-o` | auto | Output file path |
+| `--wait / --no-wait` | | `--wait` | Wait for completion or return task ID |
+| `--api-key` | | `$FREEPIK_API_KEY` | API key override |
+
+**Available models:**
+
+| Model | Description |
+|-------|-------------|
+| `flux-2-pro` | High-quality, versatile (default) |
+| `mystic` | Freepik's exclusive photorealistic workflow |
+| `flux-kontext-pro` | Instruction-based image editing (img2img) |
+| `flux-2-turbo` | Fast generation |
+| `flux-pro-1.1` | Flux Pro v1.1 |
+| `seedream-v4` | Quality generation with editing support |
+| `seedream-v4-5` | Seedream v4.5 (faster) |
+| `ideogram-v2` | Ideogram v2 |
+
+**Examples:**
+
+```bash
+freepik generate-image "a cat on the moon, oil painting style"
+freepik generate-image "cyberpunk city at night" --model mystic --aspect-ratio 16:9
+freepik generate-image "make the sky orange at sunset" --model flux-kontext-pro --input-image photo.jpg
+freepik generate-image "portrait of a wizard" --seed 42 --output wizard.jpg
+freepik generate-image "vast ocean panorama" --model flux-2-pro --no-wait
+```
+
+---
+
+### `generate-video`
+
+Animate a source image into a short video clip.
+
+```bash
+freepik generate-video <image> [OPTIONS]
+```
+
+| Option | Short | Default | Description |
+|--------|-------|---------|-------------|
+| `--model` | `-m` | `kling-o1-pro` | Video AI model |
+| `--prompt` | `-p` | — | Motion/style guidance |
+| `--duration` | `-d` | `5` | Duration in seconds (`5` or `10`) |
+| `--aspect-ratio` | `-a` | `16:9` | `16:9` \| `9:16` \| `1:1` |
+| `--seed` | | — | Seed for reproducibility |
+| `--output` | `-o` | auto | Output `.mp4` path |
+| `--wait / --no-wait` | | `--wait` | |
+| `--api-key` | | `$FREEPIK_API_KEY` | |
+
+**Available models:**
+
+| Model | Description |
+|-------|-------------|
+| `kling-o1-pro` | Best quality, first/last frame interpolation (default) |
+| `kling-o1-std` | Standard quality Kling O1 |
+| `kling-elements-pro` | Kling Elements Pro |
+| `kling-elements-std` | Kling Elements Standard |
+| `minimax-hailuo` | Minimax Hailuo 1080p |
+| `wan-2.5` | WAN 2.5 |
+| `runway-gen4` | Runway Gen4 |
+
+**Examples:**
+
+```bash
+freepik generate-video photo.jpg --prompt "gentle ocean waves lapping at the shore"
+freepik generate-video portrait.png --model minimax-hailuo --duration 10 --aspect-ratio 9:16
+freepik generate-video landscape.jpg --model kling-o1-pro --output timelapse.mp4
+```
+
+---
+
+### `upscale-image`
+
+Upscale and enhance an image using AI.
+
+```bash
+freepik upscale-image <image> [OPTIONS]
+```
+
+| Option | Short | Default | Description |
+|--------|-------|---------|-------------|
+| `--mode` | | `precision-v2` | Upscaling mode (see below) |
+| `--scale` | | `2x` | Scale factor: `2x` or `4x` |
+| `--creativity` | | — | Creative level 0–10 (creative mode only) |
+| `--prompt` | `-p` | — | Enhancement guidance (creative mode only) |
+| `--seed` | | — | Seed for reproducibility |
+| `--output` | `-o` | auto | Output file path |
+| `--wait / --no-wait` | | `--wait` | |
+| `--api-key` | | `$FREEPIK_API_KEY` | |
+
+**Modes:**
+
+| Mode | Description |
+|------|-------------|
+| `precision-v2` | Faithful, detail-preserving upscale (recommended) |
+| `precision` | Faithful upscaling |
+| `creative` | AI-enhanced creative reinterpretation |
+
+**Examples:**
+
+```bash
+freepik upscale-image photo.jpg --scale 4x
+freepik upscale-image photo.jpg --mode precision-v2 --scale 2x --output photo_hd.jpg
+freepik upscale-image portrait.jpg --mode creative --creativity 6 --prompt "sharp cinematic texture"
+```
+
+---
+
+### `upscale-video`
+
+Upscale a video to higher resolution using AI.
+
+```bash
+freepik upscale-video <video> [OPTIONS]
+```
+
+| Option | Short | Default | Description |
+|--------|-------|---------|-------------|
+| `--mode` | | `standard` | `standard` \| `turbo` (faster) |
+| `--output` | `-o` | auto | Output `.mp4` path |
+| `--wait / --no-wait` | | `--wait` | |
+| `--api-key` | | `$FREEPIK_API_KEY` | |
+
+**Examples:**
+
+```bash
+freepik upscale-video clip.mp4
+freepik upscale-video clip.mp4 --mode turbo --output clip_4k.mp4
+```
+
+---
+
+### `generate-icon`
+
+Generate an icon from a text prompt in various styles.
+
+```bash
+freepik generate-icon <prompt> [OPTIONS]
+```
+
+| Option | Short | Default | Description |
+|--------|-------|---------|-------------|
+| `--style` | `-s` | `color` | `solid` \| `outline` \| `color` \| `flat` \| `sticker` |
+| `--format` | `-f` | `png` | `png` \| `svg` |
+| `--steps` | | `30` | Inference steps (10–50) |
+| `--guidance` | | `7.5` | Guidance scale (0–10) |
+| `--seed` | | — | |
+| `--output` | `-o` | auto | |
+
+**Examples:**
+
+```bash
+freepik generate-icon "shopping cart" --style solid --format svg
+freepik generate-icon "rocket ship" --style color --format png
+freepik generate-icon "leaf" --style outline --format svg --output leaf.svg
+```
+
+---
+
+### `expand-image`
+
+Expand an image by generating new content around its edges (outpainting).
+
+```bash
+freepik expand-image <image> [OPTIONS]
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--left` | `0` | Pixels to add on the left (0–2048) |
+| `--right` | `0` | Pixels to add on the right (0–2048) |
+| `--top` | `0` | Pixels to add on top (0–2048) |
+| `--bottom` | `0` | Pixels to add on the bottom (0–2048) |
+| `--prompt` / `-p` | — | Guide the expansion content |
+| `--model` / `-m` | `flux-pro` | `flux-pro` \| `ideogram` \| `seedream-v4-5` |
+| `--seed` | — | |
+| `--output` / `-o` | auto | |
+
+**Examples:**
+
+```bash
+freepik expand-image photo.jpg --left 512 --right 512 --prompt "lush green forest"
+freepik expand-image banner.png --bottom 256 --model seedream-v4-5
+freepik expand-image portrait.jpg --top 300 --bottom 300 --prompt "studio backdrop"
+```
+
+---
+
+### `describe-image`
+
+Analyze an image and generate a descriptive text prompt for it — useful for reverse-engineering AI images or building prompt libraries.
+
+```bash
+freepik describe-image <image> [OPTIONS]
+```
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--output` | `-o` | Save the prompt text to a `.txt` file |
+| `--wait / --no-wait` | | |
+| `--api-key` | | |
+
+**Examples:**
+
+```bash
+freepik describe-image painting.jpg
+freepik describe-image scene.png --output scene_prompt.txt
+```
+
+---
+
+### `relight` *(Premium)*
+
+Relight an image using AI-controlled lighting.
+
+```bash
+freepik relight <image> [OPTIONS]
+```
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--prompt` | `-p` | Lighting description e.g. `"dramatic studio lighting"` |
+| `--style` | `-s` | Lighting style preset |
+| `--output` | `-o` | |
+
+**Examples:**
+
+```bash
+freepik relight portrait.jpg --prompt "warm golden hour sunlight from the left"
+freepik relight product.png --prompt "soft studio lighting, white background"
+```
+
+---
+
+### `style-transfer` *(Premium)*
+
+Apply the artistic style from one image onto the content of another.
+
+```bash
+freepik style-transfer <content-image> <style-image> [OPTIONS]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--strength` | Style strength 0.0–1.0 |
+| `--output` / `-o` | |
+
+**Examples:**
+
+```bash
+freepik style-transfer photo.jpg van_gogh.jpg
+freepik style-transfer portrait.png impressionist.jpg --strength 0.75 --output styled.jpg
+```
+
+---
+
+### `config`
+
+Manage CLI configuration stored at `~/.config/freepik-cli/config.toml`.
+
+```bash
+freepik config show              # Display all settings (as a table)
+freepik config show --toml       # Display as highlighted TOML
+freepik config get <key>         # Print a single value
+freepik config set <key> <value> # Update a setting
+freepik config reset             # Reset to defaults
+freepik config path              # Print the config file path
+```
+
+**Configurable keys:**
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `default_image_model` | `flux-2-pro` | Default model for `generate-image` |
+| `default_video_model` | `kling-o1-pro` | Default model for `generate-video` |
+| `default_upscale_mode` | `precision-v2` | Default mode for `upscale-image` |
+| `default_output_dir` | `.` | Directory for auto-generated output files |
+| `base_url` | `https://api.freepik.com` | API base URL |
+| `poll_timeout` | `600` | Max seconds to wait for task completion |
+| `poll_max_interval` | `15` | Max seconds between polling attempts |
+| `show_banner` | `true` | Show the ASCII art banner |
+
+> **Note:** The API key is never saved to the config file. Use `FREEPIK_API_KEY` or `--api-key`.
+
+**Examples:**
+
+```bash
+freepik config set default_image_model mystic
+freepik config set default_output_dir ~/Pictures/freepik
+freepik config set show_banner false
+freepik config set poll_timeout 300
+```
 
 ## Configuration
 
-```bash
-freepik config show
-freepik config set default_image_model mystic
-freepik config set default_output_dir ~/images
+Settings are resolved in this priority order (highest wins):
+
+1. `--api-key` / `--model` / etc. command-line flags
+2. `FREEPIK_*` environment variables (e.g. `FREEPIK_API_KEY`)
+3. `~/.config/freepik-cli/config.toml`
+4. Built-in defaults
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `FREEPIK_API_KEY` | Your Freepik API key **(required)** |
+| `FREEPIK_BASE_URL` | API base URL override |
+| `FREEPIK_DEFAULT_IMAGE_MODEL` | Default image model |
+| `FREEPIK_DEFAULT_VIDEO_MODEL` | Default video model |
+| `FREEPIK_DEFAULT_OUTPUT_DIR` | Default output directory |
+| `FREEPIK_POLL_TIMEOUT` | Task polling timeout in seconds |
+| `FREEPIK_SHOW_BANNER` | Show/hide the ASCII banner (`true`/`false`) |
+
+## Output Files
+
+When no `--output` path is provided, files are saved with an auto-generated name:
+
 ```
+freepik_image_flux-2-pro_20260408_143022.jpg
+freepik_video_kling-o1-pro_20260408_143512.mp4
+freepik_upscaled_precision-v2_20260408_144001.jpg
+```
+
+The default output directory is the current working directory. Change it with:
+
+```bash
+freepik config set default_output_dir ~/Pictures/freepik
+```
+
+## Async Workflows (`--no-wait`)
+
+Every command supports `--no-wait` to submit a task and return immediately without polling:
+
+```bash
+# Submit and get task ID instantly
+freepik generate-image "a nebula" --model mystic --no-wait
+
+# Task Queued
+# Task ID:  c3f2a1b8-...
+# Type:     image
+# Model:    mystic
+```
+
+This is useful for batching multiple requests or integrating with scripts.
+
+## Shell Completion
+
+Install tab-completion for your shell:
+
+```bash
+freepik --install-completion        # auto-detects your shell
+```
+
+Supports bash, zsh, fish, and PowerShell.
+
+## Project Structure
+
+```
+freepik/
+├── pyproject.toml
+├── .env.example
+├── freepik_cli/
+│   ├── main.py                  # CLI entry point
+│   ├── api/
+│   │   ├── client.py            # HTTP client (httpx)
+│   │   ├── models.py            # Enums, endpoint maps, response helpers
+│   │   ├── images.py            # Image generation & analysis API
+│   │   ├── videos.py            # Video generation API
+│   │   ├── upscale.py           # Image & video upscaling API
+│   │   └── edit.py              # Icon, relight, style-transfer API
+│   ├── commands/
+│   │   ├── generate.py          # generate-image, generate-video, generate-icon
+│   │   ├── upscale.py           # upscale-image, upscale-video
+│   │   ├── edit.py              # expand-image, relight, style-transfer
+│   │   ├── analyze.py           # describe-image
+│   │   └── config.py            # config management
+│   └── utils/
+│       ├── console.py           # Rich console, theme, display helpers
+│       ├── config.py            # FreepikConfig (pydantic-settings)
+│       ├── polling.py           # Live polling with Rich
+│       └── files.py             # Base64 encoding, download, path utils
+```
+
+## Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| `typer[all]` | CLI framework with Rich integration |
+| `rich` | Beautiful terminal output |
+| `httpx` | HTTP client |
+| `pydantic-settings` | Config + env var management |
+| `pillow` | Image dimension reading |
+| `platformdirs` | Cross-platform config paths |
+| `toml` | Config file format |