Freepik AI CLI

A sophisticated, beautiful command-line interface for the Freepik AI API — 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 (free tier includes $5 credit)

Setup

git clone <repo>
cd freepik

python3 -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate

pip install -e .

API Key

export FREEPIK_API_KEY=your_api_key_here

Or add it to a .env file in the project root (see .env.example).

Quick Start

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

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:

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.

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:

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.

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:

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.

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:

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.

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:

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).

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:

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.

freepik describe-image <image> [OPTIONS]

Option	Short	Description
--output	-o	Save the prompt text to a .txt file
--wait / --no-wait
--api-key

Examples:

freepik describe-image painting.jpg
freepik describe-image scene.png --output scene_prompt.txt

---

relight (Premium)

Relight an image using AI-controlled lighting.

freepik relight <image> [OPTIONS]

Option	Short	Description
--prompt	-p	Lighting description e.g. "dramatic studio lighting"
--style	-s	Lighting style preset
--output	-o

Examples:

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.

freepik style-transfer <content-image> <style-image> [OPTIONS]

Option	Description
--strength	Style strength 0.0–1.0
--output / -o

Examples:

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.

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:

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:

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:

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

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