480 lines
15 KiB
Markdown
480 lines
15 KiB
Markdown
# 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 |
|