Magnific AI CLI

A sophisticated, beautiful command-line interface for the Magnific 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 MAGNIFIC_API_KEY and go

Installation

Prerequisites

• Python 3.11+
• A Magnific API key (free tier includes $5 credit)

Setup

git clone <repo>
cd magnific

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

pip install -e .

API Key

export MAGNIFIC_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
magnific generate-image "a misty forest at dawn, cinematic lighting"

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

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

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

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

Commands

generate-image

Generate an image from a text prompt.

magnific 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		$MAGNIFIC_API_KEY	API key override

Available models:

Model	Description
flux-2-pro	High-quality, versatile (default)
mystic	Magnific'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:

magnific generate-image "a cat on the moon, oil painting style"
magnific generate-image "cyberpunk city at night" --model mystic --aspect-ratio 16:9
magnific generate-image "make the sky orange at sunset" --model flux-kontext-pro --input-image photo.jpg
magnific generate-image "portrait of a wizard" --seed 42 --output wizard.jpg
magnific generate-image "vast ocean panorama" --model flux-2-pro --no-wait

---

generate-video

Animate a source image into a short video clip.

magnific 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		$MAGNIFIC_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:

magnific generate-video photo.jpg --prompt "gentle ocean waves lapping at the shore"
magnific generate-video portrait.png --model minimax-hailuo --duration 10 --aspect-ratio 9:16
magnific generate-video landscape.jpg --model kling-o1-pro --output timelapse.mp4

---

upscale-image

Upscale and enhance an image using AI.

magnific 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		$MAGNIFIC_API_KEY

Modes:

Mode	Description
precision-v2	Faithful, detail-preserving upscale (recommended)
precision	Faithful upscaling
creative	AI-enhanced creative reinterpretation

Examples:

magnific upscale-image photo.jpg --scale 4x
magnific upscale-image photo.jpg --mode precision-v2 --scale 2x --output photo_hd.jpg
magnific upscale-image portrait.jpg --mode creative --creativity 6 --prompt "sharp cinematic texture"

---

upscale-video

Upscale a video to higher resolution using AI.

magnific 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		$MAGNIFIC_API_KEY

Examples:

magnific upscale-video clip.mp4
magnific upscale-video clip.mp4 --mode turbo --output clip_4k.mp4

---

generate-icon

Generate an icon from a text prompt in various styles.

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

magnific generate-icon "shopping cart" --style solid --format svg
magnific generate-icon "rocket ship" --style color --format png
magnific generate-icon "leaf" --style outline --format svg --output leaf.svg

---

expand-image

Expand an image by generating new content around its edges (outpainting).

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

magnific expand-image photo.jpg --left 512 --right 512 --prompt "lush green forest"
magnific expand-image banner.png --bottom 256 --model seedream-v4-5
magnific 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.

magnific describe-image <image> [OPTIONS]

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

Examples:

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

---

relight (Premium)

Relight an image using AI-controlled lighting.

magnific relight <image> [OPTIONS]

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

Examples:

magnific relight portrait.jpg --prompt "warm golden hour sunlight from the left"
magnific relight product.png --prompt "soft studio lighting, white background"

---

style-transfer (Premium)

Apply the artistic style from one image onto the content of another.

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

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

Examples:

magnific style-transfer photo.jpg van_gogh.jpg
magnific style-transfer portrait.png impressionist.jpg --strength 0.75 --output styled.jpg

---

config

Manage CLI configuration stored at ~/.config/magnific-cli/config.toml.

magnific config show              # Display all settings (as a table)
magnific config show --toml       # Display as highlighted TOML
magnific config get <key>         # Print a single value
magnific config set <key> <value> # Update a setting
magnific config reset             # Reset to defaults
magnific 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.magnific.ai	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 MAGNIFIC_API_KEY or --api-key.

Examples:

magnific config set default_image_model mystic
magnific config set default_output_dir ~/Pictures/magnific
magnific config set show_banner false
magnific config set poll_timeout 300

Configuration

Settings are resolved in this priority order (highest wins):

1. --api-key / --model / etc. command-line flags
2. MAGNIFIC_* environment variables (e.g. MAGNIFIC_API_KEY)
3. ~/.config/magnific-cli/config.toml
4. Built-in defaults

Environment Variables

Variable	Description
MAGNIFIC_API_KEY	Your Magnific API key (required)
MAGNIFIC_BASE_URL	API base URL override
MAGNIFIC_DEFAULT_IMAGE_MODEL	Default image model
MAGNIFIC_DEFAULT_VIDEO_MODEL	Default video model
MAGNIFIC_DEFAULT_OUTPUT_DIR	Default output directory
MAGNIFIC_POLL_TIMEOUT	Task polling timeout in seconds
MAGNIFIC_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:

magnific_image_flux-2-pro_20260408_143022.jpg
magnific_video_kling-o1-pro_20260408_143512.mp4
magnific_upscaled_precision-v2_20260408_144001.jpg

The default output directory is the current working directory. Change it with:

magnific config set default_output_dir ~/Pictures/magnific

Async Workflows (--no-wait)

Every command supports --no-wait to submit a task and return immediately without polling:

# Submit and get task ID instantly
magnific 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:

magnific --install-completion        # auto-detects your shell

Supports bash, zsh, fish, and PowerShell.

Project Structure

magnific/
├── pyproject.toml
├── .env.example
├── magnific_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            # MagnificConfig (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