freepik/README.md

# Freepik AI CLI

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      # 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
# Generate an image
freepik generate-image "a misty forest at dawn, cinematic lighting"

# Animate an image into a video
freepik generate-video photo.jpg --prompt "gentle camera drift" --duration 5

# Upscale an image 4x
freepik upscale-image photo.jpg --mode precision-v2 --scale 4x

# Upscale a video
freepik upscale-video clip.mp4 --mode turbo

# Describe an image (reverse-engineer its prompt)
freepik describe-image painting.jpg
```

## Commands

### `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

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 |