icon-gen-ai - Documentation

Installation

Basic Installation

pip install icon-gen-ai

With AI Features (Optional)

pip install icon-gen-ai[ai]

Note: To use the AI features, you need an API key from Anthropic, Hugging Face, or OpenAI.
Support for additional providers is coming soon.

See .env.example

ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxx
# Optional: ANTHROPIC_BASE_URL=

HUGGINGFACE_API_TOKEN=hf_xxxxxxxxxxxxx
# Optional: HF_BASE_URL=

OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxx
# Optional: OPENAI_BASE_URL=

CLI Usage

Basic Commands

Generate custom icons from Iconify, URL, and a local file:

icon-gen-ai generate material-icon-theme:python -o docs/output/gens_python.svg \
    --size 64 --bg-color ivory --outline-width 4 --outline-color mediumslateblue --border-radius 8 \
    --animation "flip-v:0.7"

icon-gen-ai generate -i 'https://upload.wikimedia.org/wikipedia/commons/a/a7/React-icon.svg' -o docs/output/gens_react.svg \
    --size 64 --bg-color ivory --outline-width 4 --outline-color mediumslateblue --border-radius 8 \
    --animation "spin:8"

icon-gen-ai generate -i 'docs/input/html_css_js.jpeg' -o docs/output/gens_hmtl_css_js.svg \
    --size 64 --bg-color ivory --outline-width 4 --outline-color mediumslateblue --border-radius 8 \
    --animation "flip-h:1"

See full terminal output

Generating icon
  Source: material-icon-theme:python
  Size: 64px
  Color: original
  Background: ivory
  Border radius: 8px
  Animation: flip-v:0.7
  Outline: 4px (mediumslateblue)

✓ Saved to docs/output/gens_python.svg


Generating icon
  Source: https://upload.wikimedia.org/wikipedia/commons/a/a7/React-icon.svg
  Size: 64px
  Color: original
  Background: ivory
  Border radius: 8px
  Animation: spin:8
  Outline: 4px (mediumslateblue)

✓ Saved to docs/output/gens_react.svg


Generating icon
  Source: docs/input/html_css_js.jpeg
  Size: 64px
  Color: original
  Background: ivory
  Border radius: 8px
  Animation: flip-h:1
  Outline: 4px (mediumslateblue)

✓ Saved to docs/output/gens_hmtl_css_js.svg

Search icons based on a natural language query and directly generate based on AI-suggestions:

icon-gen-ai search "github icon and logo" --generate

See full terminal output

Searching: github icon and logo

Using cached response (saved 696 tokens)
1. simple-icons:github
   This is the official GitHub logo, perfect for representing the brand directly.

2. mdi:git
   This icon represents Git, which is the underlying version control system used by GitHub.

Generating icons...

Show available providers and active LLM:

icon-gen-ai providers

Installed providers: openai, anthropic, huggingface
✓ Active: openai (gpt-4o-mini)

CLI Options

CLI Demo

generate_icon()

Generate a single icon with full customization.

Signature

generate_icon(
    icon_name: Optional[str] = None,
    direct_url: Optional[str] = None,
    local_file: Optional[str] = None,
    output_name: Optional[str] = None,
    format: str = "svg",
    size: Optional[int] = None,
    scale: Optional[float] = None,
    color: Optional[Union[str, tuple[str, str]]] = None,
    direction: str = "horizontal",
    bg_color: Optional[Union[str, tuple[str, str]]] = None,
    bg_direction: str = "horizontal",
    border_radius: int = 0,
    outline_width: int = 0,
    outline_color: Optional[str] = None,
    animation: Optional[Union[str, dict]] = None,
) -> Optional[Path]

Info: Provide one input source: icon_name, direct_url, or local_file.

Basic Example

Initialize the icon generator and create a star icon with an embedded SVG animation:

from icon_gen_ai import IconGenerator

  gen = IconGenerator(output_dir="docs")

  gen.generate_icon(
      icon_name="meteocons:star-fill",
      size=64,
      bg_color="navy",
      border_radius=4,
      output_name="output/star-fill"
  )

generate_batch()

Generate multiple icons at once with shared default settings:

Signature

generate_batch(
    icons: dict[str, str | dict],
    size: Optional[int] = None,
    scale: Optional[float] = None,
    color: Optional[Union[str, tuple[str, str]]] = None,
    direction: str = "horizontal",
    bg_color: Optional[Union[str, tuple[str, str]]] = None,
    bg_direction: str = "horizontal",
    border_radius: int = 0,
    outline_width: int = 0,
    outline_color: Optional[str] = None,
    animation: Optional[Union[str, dict]] = None,
) -> list[Path]

Basic Example

Create a series of icons from different sources with the same styling:

from icon_gen_ai import IconGenerator

gen = IconGenerator(output_dir="docs")

ai_icons = {
    'output/genb_openai': 'simple-icons:openai',
    'output/genb_claude': 'simple-icons:claude',
    'output/genb_googlegemini': 'simple-icons:googlegemini',
    'output/genb_mistralai': 'simple-icons:mistralai',
    'output/genb_llama': 'simple-icons:meta',
    'output/genb_deepseek': {
        'local_file': 'input/deepseek-icon.png'
    },
    'output/genb_nemotron': {
        'url': 'https://companieslogo.com/img/orig/NVDA-df4c2377.svg'
    },
}

gen.generate_batch(
    ai_icons, 
    color='deepskyblue', 
    size=64, 
    outline_color='deepskyblue', 
    outline_width=4, 
    border_radius=8
  )

discover_icons()

Show available providers and active LLM:

icon-gen-ai providers

Installed providers: openai, anthropic
    ✓ Active: openai (gpt-4o-mini)

Note: To use the AI features, you need an API key from Anthropic, Hugging Face, or OpenAI.
Support for additional providers is coming soon.

Signature

discover_icons(
      query: str,
      context: Optional[dict] = None
  ) -> IconDiscoveryResponse

Basic Example

from icon_gen_ai import IconAssistant

assistant = IconAssistant()

response = assistant.discover_icons(
    "icons for a payment checkout page"
)

print(response.explanation)

for suggestion in response.suggestions:
    print(
        suggestion.icon_name,
        suggestion.confidence,
        suggestion.reason
    )

See full terminal output

Querying Iconify using openai (model: gpt-4o-mini)...
Used 963 tokens (≈$0.0003)
The icons suggested are essential for a payment checkout page, representing different payment methods and actions a user might take.
fa6-solid:credit-card 0.95 This icon represents credit card payments, which are commonly used in online transactions.
mdi:paypal 0.95 The PayPal icon signifies the option to pay using this popular online payment service.
fa6-solid:cash-register 0.9 This icon indicates cash payment options, which can be relevant for certain checkout scenarios.
mdi:bank 0.9 The bank icon can represent bank transfers, an important payment method.
fa6-solid:lock 0.92 A lock icon conveys security, which is crucial for assuring users their payment information is safe.

With Design Context

from icon_gen_ai import IconAssistant

assistant = IconAssistant()

response = assistant.discover_icons(
      "finance dashboard navigation icons",
      context={
          "project_type": "SaaS dashboard",
          "design_style": "modern",
          "color_scheme": "blue and purple"
      }
  )

print(response.explanation)

for suggestion in response.suggestions:
    print(
        suggestion.icon_name,
        suggestion.confidence,
        suggestion.use_case,
        suggestion.reason,
        suggestion.style_suggestions
    )

See full terminal output

Querying Iconify using openai (model: gpt-4o-mini)...
Used 941 tokens (≈$0.0003)
The selected icons are ideal for a finance dashboard as they represent key functions and data visualizations commonly used in financial applications. They align with a modern design style and complement a blue and purple color scheme.
mdi:view-dashboard 0.95 Use this icon for the main dashboard navigation link. This icon represents an overview of the dashboard, making it perfect for navigation. {'color': 'white', 'size': 256, 'bg_color': 'mediumslateblue', 'border_radius': 0}
mdi:chart-line 0.95 Ideal for sections displaying financial performance or trends. This icon symbolizes financial trends and analysis, which is crucial for finance dashboards. {'color': 'white', 'size': 256, 'bg_color': 'mediumslateblue', 'border_radius': 0}
mdi:table 0.95 Use this icon for sections that present tabular financial data. Represents structured data, which is essential for displaying financial reports or transactions. {'color': 'white', 'size': 256, 'bg_color': 'mediumslateblue', 'border_radius': 0}
heroicons:chart-bar 0.95 Suitable for sections highlighting key financial indicators or comparisons. This icon is associated with data visualization, perfect for displaying financial metrics. {'color': 'white', 'size': 256, 'bg_color': 'mediumslateblue', 'border_radius': 0}
lucide:layout-dashboard 0.95 Can be used for layout settings or customizable dashboard options. Represents a grid layout, which is typical in modern dashboards, enhancing user navigation. {'color': 'white', 'size': 256, 'bg_color': 'mediumslateblue', 'border_radius': 0}

Returned Data

Each suggestion contains rich metadata to help you decide which icon to use.

IconSuggestion:
  - icon_name: str
  - reason: str
  - use_case: str
  - confidence: float
  - style_suggestions: dict | None

End-to-End Example

Discover icons with AI and immediately generate them with consistent styling.

from icon_gen_ai import IconAssistant, IconGenerator

assistant = IconAssistant()
generator = IconGenerator(output_dir="docs/output")

response = assistant.discover_icons(
    "payment provider logos"
)

for i, suggestion in enumerate(response.suggestions, 1):
    generator.generate_icon(
        icon_name=suggestion.icon_name,
        output_name=f"payment_{i}",
        color="white",
        bg_color=('deeppink','mediumslateblue'),
        size=64,
        border_radius=8
    )

Color Options

Solid Colors

You can specify the color of your icon using any valid CSS color name supported by Pillow (Python Imaging Library). This includes all named CSS colors such as white, black, etc. There are currently 140+ named colors available.

You can also use hex color codes or RGB colors to specify the icon color. Tip: You can also use any CSS color picker to get hex or RGB values.

Skip providing color or set color=None to keep the original icon colors. Examples:

from icon_gen_ai import IconGenerator

gen = IconGenerator(output_dir="docs/output")

# Color name
gen.generate_icon(icon_name="gis:search-data", color="deepskyblue")

# Hex colors
gen.generate_icon(icon_name="mdi:star", color="#FFD700")  # gold

# RGB colors
gen.generate_icon(icon_name="fluent:heart-pulse-24-filled", color="rgb(255, 0, 0)")  # red

gen.generate_icon(
    icon_name="material-icon-theme:folder-download-open",
    color=None,  # or skip to preserve original colors
)

Gradients

You can apply gradients to your icons by passing a tuple of two colors to the color or bg_color parameters. The direction and bg_direction options let you control the orientation of the gradient: horizontal (default), vertical, diagonal, or radial (center-out).

from icon_gen_ai import IconGenerator

gen = IconGenerator(output_dir="docs/output")
size = 64
border_radius = 8

# Icon gradient with default (horizontal) direction
gen.generate_icon(
    icon_name="cryptocurrency:bch", 
    color=("gold", "crimson"), 
    bg_color="ivory", 
    size=size, 
    border_radius=border_radius
)

# Icon gradient with vertical direction
gen.generate_icon(
    icon_name="cryptocurrency:eth", 
    color=("royalblue", "violet"), 
    direction="vertical", 
    bg_color="ivory", 
    size=size, 
    border_radius=border_radius
) 

# Background gradient with diagonal direction
gen.generate_icon(
    icon_name="cryptocurrency:bnb", 
    color="ivory", 
    bg_color=("gold", "crimson"), 
    bg_direction="diagonal", 
    size=size, 
    border_radius=border_radius
) 

# Icon and background gradients with different directions
gen.generate_icon(
    icon_name="cryptocurrency:usdc", 
    color=("aqua", "indigo"), 
    direction="diagonal", 
    bg_color=("lime", "white"), 
    bg_direction="vertical", 
    size=size, 
    border_radius=border_radius
)

# Radial gradient icon (center-out)
gen.generate_icon(
    icon_name="ph:star-bold",
    color=("deeppink", "deepskyblue"),
    direction="radial",
    bg_color="#1a1a2e",
    size=size,
    border_radius=border_radius
)

# Radial gradient background
gen.generate_icon(
    icon_name="ph:fire-bold",
    color="white",
    bg_color=("deeppink", "deepskyblue"),
    bg_direction="radial",
    size=size,
    border_radius=border_radius
)