img-cli 0.1.0__py3-none-any.whl

img_cli/__init__.py

@@ -0,0 +1,13 @@
+"""img-cli: CLI tool for OpenAI-compatible Image Generation and Editing."""
+
+try:
+    from img_cli._version import __version__, __version_tuple__
+except ImportError:
+    try:
+        from importlib.metadata import version
+
+        __version__ = version("img-cli")
+        __version_tuple__ = (0, 0, 0)
+    except Exception:
+        __version__ = "0.0.0.dev0"
+        __version_tuple__ = (0, 0, 0, "dev0")

img_cli/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

img_cli/cli.py

@@ -0,0 +1,264 @@
+"""Command line interface for img-cli."""
+
+import sys
+import time
+
+import click
+from rich.console import Console
+
+from img_cli import __version__
+from img_cli.client import ImageClient
+from img_cli.config import AuthError, load_auth_config
+from img_cli.image_utils import save_images
+from img_cli.logger import create_audit_record, log_audit
+
+console = Console()
+err_console = Console(stderr=True)
+
+
+@click.group(context_settings={"help_option_names": ["-h", "--help"]})
+@click.version_option(version=__version__, message="img-cli %(version)s")
+def main():
+    """img-cli: 通过 OpenAI Images API 生成或编辑图片。"""
+
+
+@main.command(name="generate", help="根据文字描述生成图片。")
+@click.argument("prompt", type=str)
+@click.option(
+    "-m",
+    "--model",
+    default="gpt-image-2",
+    show_default=True,
+    help="模型名称（如 gpt-image-2, dall-e-3）",
+)
+@click.option(
+    "-s",
+    "--size",
+    default="1024x1024",
+    show_default=True,
+    help="图片尺寸（如 1024x1024, 1536x1024, 1024x1536, auto）",
+)
+@click.option(
+    "-q", "--quality", default=None, help="质量设置（low/medium/high/auto 或 standard/hd）"
+)
+@click.option("-n", "--n", default=1, type=int, show_default=True, help="生成数量")
+@click.option("-o", "--output", default=".", show_default=True, help="输出目录")
+@click.option(
+    "--format",
+    "format_",
+    default="png",
+    show_default=True,
+    type=click.Choice(["png", "jpeg", "webp"], case_sensitive=False),
+    help="输出格式",
+)
+def generate(
+    prompt: str,
+    model: str,
+    size: str,
+    quality: str | None,
+    n: int,
+    output: str,
+    format_: str,
+):
+    """根据文字描述生成图片。"""
+    start_time = time.time()
+    saved_files: list[str] = []
+    error_msg: str | None = None
+    revised_prompt: str | None = None
+
+    try:
+        auth = load_auth_config()
+    except AuthError as e:
+        err_console.print(f"[bold red]{e}[/bold red]")
+        sys.exit(1)
+
+    try:
+        console.print(f"[cyan]正在请求模型 [bold]{model}[/bold] 生成图片...[/cyan]")
+        client = ImageClient(auth)
+        result = client.generate(
+            prompt=prompt,
+            model=model,
+            size=size,
+            quality=quality,
+            n=n,
+        )
+        revised_prompt = result.revised_prompt
+
+        # Save images
+        saved_paths = save_images(result.images_bytes, output_dir=output, format=format_)
+        saved_files = [str(p) for p in saved_paths]
+
+        duration = time.time() - start_time
+
+        # Print revised prompt if available
+        if revised_prompt:
+            console.print("\n[bold yellow]优化后的 Prompt (revised_prompt):[/bold yellow]")
+            console.print(f"[dim]{revised_prompt}[/dim]")
+
+        # Print success info
+        console.print(f"\n[bold green]✓ 成功生成 {len(saved_files)} 张图片:[/bold green]")
+        for f in saved_files:
+            console.print(f"  - [underline]{f}[/underline]")
+        console.print(f"[dim]耗时: {duration:.2f} 秒[/dim]")
+
+        # Log success audit
+        audit = create_audit_record(
+            command="generate",
+            prompt=prompt,
+            model=model,
+            duration_seconds=duration,
+            status="success",
+            size=size,
+            quality=quality,
+            n=n,
+            output_dir=output,
+            files=saved_files,
+            revised_prompt=revised_prompt,
+        )
+        log_audit(audit)
+
+    except Exception as e:
+        duration = time.time() - start_time
+        error_msg = str(e)
+        err_console.print(f"[bold red]生成图片失败:[/bold red] {error_msg}")
+
+        # Log error audit
+        audit = create_audit_record(
+            command="generate",
+            prompt=prompt,
+            model=model,
+            duration_seconds=duration,
+            status="error",
+            size=size,
+            quality=quality,
+            n=n,
+            output_dir=output,
+            error=error_msg,
+        )
+        log_audit(audit)
+        sys.exit(1)
+
+
+@main.command(name="edit", help="根据文字描述修改已有图片。支持本地文件路径和网络图片 URL。")
+@click.argument("prompt", type=str)
+@click.option("-i", "--image", "image_path", required=True, help="原图路径或 HTTP URL")
+@click.option("--mask", default=None, help="蒙版图路径或 HTTP URL（PNG，透明区域为待编辑区域）")
+@click.option(
+    "-m",
+    "--model",
+    default="gpt-image-2",
+    show_default=True,
+    help="模型名称（如 gpt-image-2, dall-e-2）",
+)
+@click.option("-s", "--size", default="auto", show_default=True, help="尺寸（如 auto, 1024x1024）")
+@click.option(
+    "-q", "--quality", default="auto", show_default=True, help="质量（如 auto, low, medium, high）"
+)
+@click.option("-n", "--n", default=1, type=int, show_default=True, help="生成数量")
+@click.option("-o", "--output", default=".", show_default=True, help="输出目录")
+@click.option(
+    "--format",
+    "format_",
+    default="png",
+    show_default=True,
+    type=click.Choice(["png", "jpeg", "webp"], case_sensitive=False),
+    help="输出格式",
+)
+def edit(
+    prompt: str,
+    image_path: str,
+    mask: str | None,
+    model: str,
+    size: str,
+    quality: str,
+    n: int,
+    output: str,
+    format_: str,
+):
+    """根据文字描述修改已有图片。"""
+    start_time = time.time()
+    saved_files: list[str] = []
+    error_msg: str | None = None
+    revised_prompt: str | None = None
+
+    try:
+        auth = load_auth_config()
+    except AuthError as e:
+        err_console.print(f"[bold red]{e}[/bold red]")
+        sys.exit(1)
+
+    try:
+        console.print(f"[cyan]正在使用模型 [bold]{model}[/bold] 编辑图片...[/cyan]")
+        client = ImageClient(auth)
+        result = client.edit(
+            prompt=prompt,
+            image_source=image_path,
+            mask_source=mask,
+            model=model,
+            size=size,
+            quality=quality,
+            n=n,
+        )
+        revised_prompt = result.revised_prompt
+
+        # Save images
+        saved_paths = save_images(result.images_bytes, output_dir=output, format=format_)
+        saved_files = [str(p) for p in saved_paths]
+
+        duration = time.time() - start_time
+
+        # Print revised prompt if available
+        if revised_prompt:
+            console.print("\n[bold yellow]优化后的 Prompt (revised_prompt):[/bold yellow]")
+            console.print(f"[dim]{revised_prompt}[/dim]")
+
+        # Print success info
+        console.print(f"\n[bold green]✓ 成功编辑并保存 {len(saved_files)} 张图片:[/bold green]")
+        for f in saved_files:
+            console.print(f"  - [underline]{f}[/underline]")
+        console.print(f"[dim]耗时: {duration:.2f} 秒[/dim]")
+
+        # Log success audit
+        audit = create_audit_record(
+            command="edit",
+            prompt=prompt,
+            model=model,
+            duration_seconds=duration,
+            status="success",
+            size=size,
+            quality=quality,
+            n=n,
+            output_dir=output,
+            input_image=image_path,
+            mask=mask,
+            files=saved_files,
+            revised_prompt=revised_prompt,
+        )
+        log_audit(audit)
+
+    except Exception as e:
+        duration = time.time() - start_time
+        error_msg = str(e)
+        err_console.print(f"[bold red]编辑图片失败:[/bold red] {error_msg}")
+
+        # Log error audit
+        audit = create_audit_record(
+            command="edit",
+            prompt=prompt,
+            model=model,
+            duration_seconds=duration,
+            status="error",
+            size=size,
+            quality=quality,
+            n=n,
+            output_dir=output,
+            input_image=image_path,
+            mask=mask,
+            error=error_msg,
+        )
+        log_audit(audit)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

img_cli/client.py

@@ -0,0 +1,189 @@
+"""OpenAI Images API client wrapper for generate and edit operations."""
+
+import base64
+import time
+from dataclasses import dataclass
+
+from openai import OpenAI
+
+from img_cli.config import AuthConfig
+from img_cli.image_utils import ensure_png_bytes, fetch_image_data
+
+
+@dataclass
+class GenerationResult:
+    images_bytes: list[bytes]
+    revised_prompt: str | None = None
+    duration_seconds: float = 0.0
+
+
+class ImageClient:
+    """Wrapper around OpenAI Images API."""
+
+    def __init__(self, auth: AuthConfig, timeout: float = 300.0):
+        self.auth = auth
+        self.client = OpenAI(
+            api_key=auth.api_key,
+            base_url=auth.api_base,
+            timeout=timeout,
+        )
+
+    def _extract_images(self, response_data: list) -> tuple[list[bytes], str | None]:
+        """Extract raw image bytes and revised_prompt from API response data."""
+        images_bytes: list[bytes] = []
+        revised_prompt: str | None = None
+
+        for item in response_data:
+            if hasattr(item, "revised_prompt") and item.revised_prompt:
+                revised_prompt = item.revised_prompt
+
+            if getattr(item, "b64_json", None):
+                images_bytes.append(base64.b64decode(item.b64_json))
+            elif getattr(item, "url", None):
+                # Download image from URL
+                data = fetch_image_data(item.url)
+                images_bytes.append(data)
+            else:
+                raise ValueError("API 响应中未包含有效的 b64_json 或 url 数据")
+
+        return images_bytes, revised_prompt
+
+    def generate(
+        self,
+        prompt: str,
+        model: str = "gpt-image-2",
+        size: str | None = "1024x1024",
+        quality: str | None = None,
+        n: int = 1,
+        response_format: str = "b64_json",
+    ) -> GenerationResult:
+        """Generate images from prompt.
+
+        Args:
+            prompt: Text description of the image.
+            model: Model name (gpt-image-2, dall-e-3, etc.).
+            size: Image dimensions (e.g. 1024x1024, auto).
+            quality: Quality setting (low/medium/high/auto or standard/hd).
+            n: Number of images to generate.
+            response_format: 'b64_json' or 'url'.
+        """
+        start_time = time.time()
+        kwargs: dict = {
+            "model": model,
+            "prompt": prompt,
+            "n": n,
+        }
+
+        # Size handling
+        if size and size.lower() != "auto":
+            kwargs["size"] = size
+        elif model.startswith("gpt-image"):
+            # gpt-image models support 'auto' size
+            kwargs["size"] = size or "1024x1024"
+        elif size and size.lower() == "auto":
+            # For dall-e models, 'auto' is not accepted, fallback to 1024x1024
+            kwargs["size"] = "1024x1024"
+
+        # Quality handling
+        if quality:
+            if model == "dall-e-3":
+                # dall-e-3 only accepts standard or hd
+                if quality.lower() in ("hd", "high"):
+                    kwargs["quality"] = "hd"
+                else:
+                    kwargs["quality"] = "standard"
+            elif model == "dall-e-2":
+                # dall-e-2 does not support quality
+                pass
+            else:
+                kwargs["quality"] = quality
+
+        # Response format
+        if response_format:
+            kwargs["response_format"] = response_format
+
+        # For dall-e-3, n must be 1
+        if model == "dall-e-3":
+            kwargs["n"] = 1
+
+        response = self.client.images.generate(**kwargs)
+        duration = time.time() - start_time
+
+        images_bytes, revised_prompt = self._extract_images(response.data)
+        return GenerationResult(
+            images_bytes=images_bytes,
+            revised_prompt=revised_prompt,
+            duration_seconds=duration,
+        )
+
+    def edit(
+        self,
+        prompt: str,
+        image_source: str,
+        mask_source: str | None = None,
+        model: str = "gpt-image-2",
+        size: str | None = "auto",
+        quality: str | None = "auto",
+        n: int = 1,
+        response_format: str = "b64_json",
+    ) -> GenerationResult:
+        """Edit an existing image using text prompt and optional mask.
+
+        Args:
+            prompt: Text description of the modification.
+            image_source: Local path or HTTP URL of the input image.
+            mask_source: Optional local path or HTTP URL of the mask image.
+            model: Model name.
+            size: Size parameter.
+            quality: Quality parameter.
+            n: Number of images.
+            response_format: 'b64_json' or 'url'.
+        """
+        start_time = time.time()
+
+        # Fetch and prepare base image
+        raw_image = fetch_image_data(image_source)
+        png_image = ensure_png_bytes(raw_image)
+
+        kwargs: dict = {
+            "model": model,
+            "prompt": prompt,
+            "image": ("image.png", png_image, "image/png"),
+            "n": n,
+        }
+
+        # Mask handling
+        if mask_source:
+            raw_mask = fetch_image_data(mask_source)
+            png_mask = ensure_png_bytes(raw_mask, force_rgba=True)
+            kwargs["mask"] = ("mask.png", png_mask, "image/png")
+
+        # Size handling
+        if size and size.lower() != "auto":
+            kwargs["size"] = size
+        elif model.startswith("gpt-image"):
+            if size:
+                kwargs["size"] = size
+        elif size and size.lower() == "auto":
+            # For dall-e-2, size must be explicit
+            kwargs["size"] = "1024x1024"
+
+        # Quality handling
+        if quality and quality.lower() != "auto":
+            if model != "dall-e-2":
+                kwargs["quality"] = quality
+        elif quality and model.startswith("gpt-image"):
+            kwargs["quality"] = quality
+
+        if response_format:
+            kwargs["response_format"] = response_format
+
+        response = self.client.images.edit(**kwargs)
+        duration = time.time() - start_time
+
+        images_bytes, revised_prompt = self._extract_images(response.data)
+        return GenerationResult(
+            images_bytes=images_bytes,
+            revised_prompt=revised_prompt,
+            duration_seconds=duration,
+        )

img_cli/config.py

@@ -0,0 +1,71 @@
+"""Configuration and authentication management for img-cli."""
+
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+AUTH_DIR = Path.home() / ".img_gen"
+AUTH_FILE = AUTH_DIR / "auth.json"
+DEFAULT_API_BASE = "https://api.openai.com/v1"
+
+
+class AuthError(Exception):
+    """Raised when authentication credentials cannot be found or are invalid."""
+
+
+@dataclass
+class AuthConfig:
+    api_key: str
+    api_base: str = DEFAULT_API_BASE
+
+
+def load_auth_config(custom_auth_file: Path | None = None) -> AuthConfig:
+    """Load authentication credentials from auth.json or environment variables.
+
+    Loading precedence:
+    1. ~/.img_gen/auth.json (or custom_auth_file if specified)
+    2. Environment variables (OPENAI_API_KEY / IMG_GEN_API_KEY, OPENAI_BASE_URL / OPENAI_API_BASE)
+
+    Raises:
+        AuthError: If no valid credentials can be found.
+    """
+    target_file = custom_auth_file or AUTH_FILE
+    api_key: str | None = None
+    api_base: str | None = None
+
+    if target_file.exists() and target_file.is_file():
+        try:
+            with open(target_file, encoding="utf-8") as f:
+                data = json.load(f)
+                if isinstance(data, dict):
+                    api_key = data.get("api_key")
+                    api_base = data.get("api_base") or data.get("base_url")
+        except Exception as e:
+            raise AuthError(f"读取认证文件失败 ({target_file}): {e}") from e
+
+    # Fallback to environment variables if not found in file
+    if not api_key:
+        api_key = os.environ.get("IMG_GEN_API_KEY") or os.environ.get("OPENAI_API_KEY")
+
+    if not api_base:
+        api_base = (
+            os.environ.get("IMG_GEN_API_BASE")
+            or os.environ.get("OPENAI_BASE_URL")
+            or os.environ.get("OPENAI_API_BASE")
+            or DEFAULT_API_BASE
+        )
+
+    if not api_key or not api_key.strip():
+        error_msg = (
+            "未找到认证文件\n"
+            "请创建配置文件 ~/.img_gen/auth.json：\n"
+            "  mkdir -p ~/.img_gen\n"
+            '  echo \'{"api_key":"sk-xxx","api_base":"https://api.openai.com/v1"}\' > ~/.img_gen/auth.json'
+        )
+        raise AuthError(error_msg)
+
+    # Normalize api_base (strip trailing slash)
+    api_base = api_base.rstrip("/")
+
+    return AuthConfig(api_key=api_key.strip(), api_base=api_base)

img_cli/image_utils.py

@@ -0,0 +1,159 @@
+"""Image utilities for fetching, format conversion, and saving."""
+
+import io
+from datetime import datetime
+from pathlib import Path
+
+import httpx
+from PIL import Image
+
+
+class ImageFetchError(Exception):
+    """Raised when an image cannot be fetched or read."""
+
+
+def fetch_image_data(source: str, timeout: float = 60.0) -> bytes:
+    """Fetch image bytes from a local path or a remote HTTP/HTTPS URL.
+
+    Args:
+        source: Local file path (e.g. ~/Desktop/img.png) or URL (http/https).
+        timeout: Request timeout for URL downloads in seconds.
+
+    Returns:
+        Image bytes.
+
+    Raises:
+        ImageFetchError: If the file does not exist or URL download fails.
+    """
+    if source.startswith(("http://", "https://")):
+        try:
+            with httpx.Client(timeout=timeout, follow_redirects=True) as client:
+                response = client.get(source)
+                response.raise_for_status()
+                return response.content
+        except httpx.HTTPStatusError as e:
+            raise ImageFetchError(f"下载图片失败 (HTTP {e.response.status_code}): {source}") from e
+        except Exception as e:
+            raise ImageFetchError(f"下载图片失败: {source} ({e})") from e
+    else:
+        path = Path(source).expanduser().resolve()
+        if not path.exists():
+            raise ImageFetchError(f"图片文件不存在: {source}")
+        if not path.is_file():
+            raise ImageFetchError(f"指定路径不是文件: {source}")
+        try:
+            return path.read_bytes()
+        except Exception as e:
+            raise ImageFetchError(f"读取图片文件失败 ({path}): {e}") from e
+
+
+def ensure_png_bytes(image_data: bytes, force_rgba: bool = False) -> bytes:
+    """Ensure the given image data is in valid PNG format (required by OpenAI Edit API).
+
+    Args:
+        image_data: Raw image bytes.
+        force_rgba: If True, convert image mode to RGBA.
+
+    Returns:
+        PNG image bytes.
+    """
+    try:
+        img = Image.open(io.BytesIO(image_data))
+        # If it's already PNG and mode matches, check if conversion needed
+        if img.format == "PNG" and (not force_rgba or img.mode == "RGBA"):
+            return image_data
+
+        target_mode = "RGBA" if (force_rgba or "A" in img.mode) else "RGB"
+        if img.mode != target_mode:
+            img = img.convert(target_mode)
+
+        buf = io.BytesIO()
+        img.save(buf, format="PNG")
+        return buf.getvalue()
+    except Exception as e:
+        raise ValueError(f"处理图片格式失败: {e}") from e
+
+
+def convert_and_save_image(
+    image_data: bytes,
+    target_path: Path,
+    target_format: str = "png",
+) -> Path:
+    """Save image bytes to target_path, converting format if requested."""
+    fmt = target_format.lower().strip(".")
+    if fmt == "jpg":
+        fmt = "jpeg"
+
+    try:
+        img = Image.open(io.BytesIO(image_data))
+        orig_fmt = (img.format or "").lower()
+        if orig_fmt == "jpg":
+            orig_fmt = "jpeg"
+
+        # If formats already match, write directly
+        if orig_fmt == fmt:
+            target_path.write_bytes(image_data)
+            return target_path
+
+        # Handle RGBA conversion for JPEG
+        if fmt == "jpeg" and img.mode in ("RGBA", "LA", "P"):
+            background = Image.new("RGB", img.size, (255, 255, 255))
+            if img.mode == "RGBA":
+                background.paste(img, mask=img.split()[3])
+            else:
+                background.paste(img.convert("RGBA"))
+            background.save(target_path, format="JPEG", quality=95)
+        else:
+            save_format = "JPEG" if fmt == "jpeg" else fmt.upper()
+            img.save(target_path, format=save_format)
+
+        return target_path
+    except Exception:
+        # Fallback to direct bytes write if Pillow fails
+        target_path.write_bytes(image_data)
+        return target_path
+
+
+def save_images(
+    images_data: list[bytes],
+    output_dir: str | Path = ".",
+    format: str = "png",
+) -> list[Path]:
+    """Save a list of image byte buffers to output directory with standard naming.
+
+    File naming format: img_<timestamp>_<index>.<format>
+    Example: img_20260829_210700_1.png
+
+    Args:
+        images_data: List of raw image data bytes.
+        output_dir: Directory path to save files into.
+        format: Target image extension/format ('png', 'jpeg', 'webp').
+
+    Returns:
+        List of absolute Paths of the saved images.
+    """
+    out_dir = Path(output_dir).expanduser().resolve()
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    fmt = format.lower().strip(".")
+    ext = "jpg" if fmt == "jpeg" else fmt
+
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    saved_paths: list[Path] = []
+
+    for i, data in enumerate(images_data, start=1):
+        filename = f"img_{timestamp}_{i}.{ext}"
+        target_path = out_dir / filename
+
+        # Handle conflict if file already exists in current second
+        if target_path.exists():
+            counter = 1
+            while target_path.exists():
+                filename = f"img_{timestamp}_{i}_{counter}.{ext}"
+                target_path = out_dir / filename
+                counter += 1
+
+        saved_file = convert_and_save_image(data, target_path, target_format=fmt)
+        saved_paths.append(saved_file)
+
+    return saved_paths

img_cli/logger.py

@@ -0,0 +1,90 @@
+"""Audit logging for img-cli operations (JSON Lines format)."""
+
+import json
+from dataclasses import asdict, dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+
+LOG_DIR = Path.home() / ".img_gen"
+LOG_FILE = LOG_DIR / "img.log"
+
+
+@dataclass
+class AuditRecord:
+    timestamp: str
+    command: str
+    prompt: str
+    model: str
+    size: str | None = None
+    quality: str | None = None
+    n: int = 1
+    output_dir: str = "."
+    input_image: str | None = None
+    mask: str | None = None
+    status: str = "success"
+    duration_seconds: float = 0.0
+    files: list[str] | None = None
+    revised_prompt: str | None = None
+    error: str | None = None
+
+
+def log_audit(
+    record: AuditRecord,
+    custom_log_file: Path | None = None,
+) -> None:
+    """Append an audit record to the JSON Lines log file.
+
+    Args:
+        record: The AuditRecord to serialize and write.
+        custom_log_file: Optional path override for testing.
+    """
+    target_file = custom_log_file or LOG_FILE
+    try:
+        target_file.parent.mkdir(parents=True, exist_ok=True)
+        data = asdict(record)
+        # Ensure files is a list
+        if data.get("files") is None:
+            data["files"] = []
+
+        line = json.dumps(data, ensure_ascii=False)
+        with open(target_file, "a", encoding="utf-8") as f:
+            f.write(line + "\n")
+    except Exception:
+        # Non-fatal: logging failure should not crash the command
+        pass
+
+
+def create_audit_record(
+    command: str,
+    prompt: str,
+    model: str,
+    duration_seconds: float,
+    status: str = "success",
+    size: str | None = None,
+    quality: str | None = None,
+    n: int = 1,
+    output_dir: str = ".",
+    input_image: str | None = None,
+    mask: str | None = None,
+    files: list[str] | None = None,
+    revised_prompt: str | None = None,
+    error: str | None = None,
+) -> AuditRecord:
+    """Helper to create an AuditRecord with current UTC timestamp."""
+    return AuditRecord(
+        timestamp=datetime.now(timezone.utc).isoformat(),
+        command=command,
+        prompt=prompt,
+        model=model,
+        size=size,
+        quality=quality,
+        n=n,
+        output_dir=output_dir,
+        input_image=input_image,
+        mask=mask,
+        status=status,
+        duration_seconds=round(duration_seconds, 2),
+        files=files or [],
+        revised_prompt=revised_prompt,
+        error=error,
+    )

img_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,139 @@
+Metadata-Version: 2.5
+Name: img-cli
+Version: 0.1.0
+Summary: CLI tool for OpenAI-compatible Image Generation and Editing
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1.7
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: openai>=1.50.0
+Requires-Dist: pillow>=10.2.0
+Requires-Dist: pydantic>=2.6.0
+Requires-Dist: rich>=13.7.0
+Description-Content-Type: text/markdown
+
+# img-cli
+
+命令行图片生成与编辑工具，基于 Python + uv 开发，封装 OpenAI 兼容的 Images API（文生图 `generate` 与图生图编辑 `edit`）。
+
+<p align="center">
+  <img src="assets/poster.png" alt="img-cli Poster" width="600" />
+</p>
+
+---
+
+## 特性
+
+- 🚀 **简单易用**：一行命令完成图片生成和图片编辑。
+- 🔑 **灵活认证**：支持 `~/.img_gen/auth.json` 配置文件及环境变量。
+- 📝 **审计日志**：自动在 `~/.img_gen/img.log` 记录每次请求详情（JSON Lines 格式）。
+- 🖼️ **格式与尺寸自适应**：支持 PNG / JPEG / WEBP，自动进行 RGBA 蒙版和格式转换。
+- 🌐 **网络与本地图片支持**：编辑模式下原图和蒙版均支持本地路径（含 `~`）及 HTTP/HTTPS URL。
+- 🤖 **Agent 友好**：清晰的标准输出与结构化错误码，便于自动化工作流接入。
+
+---
+
+## 安装与环境准备
+
+### 通过 PyPI 安装
+
+```bash
+# 使用 uv 工具安装（推荐）
+uv tool install img-cli
+
+# 或通过 pip 安装
+pip install img-cli
+```
+
+### 本地开发与运行
+
+```bash
+# 1. 运行测试 / 调试
+uv run img-cli --help
+
+# 2. 从源码安装 CLI
+uv tool install .
+```
+
+---
+
+## 认证配置
+
+首次使用前，请创建配置文件 `~/.img_gen/auth.json`：
+
+```bash
+mkdir -p ~/.img_gen
+echo '{"api_key":"sk-xxx","api_base":"https://api.openai.com/v1"}' > ~/.img_gen/auth.json
+```
+
+也可通过环境变量传入：
+- `OPENAI_API_KEY`（或 `IMG_GEN_API_KEY`）
+- `OPENAI_BASE_URL`（或 `OPENAI_API_BASE` / `IMG_GEN_API_BASE`）
+
+---
+
+## 快速使用
+
+### 1. 文生图 (generate)
+
+```bash
+# 基础生成（默认模型 gpt-image-2，保存至当前目录）
+img-cli generate "一只戴墨镜的猫坐在沙滩上"
+
+# 指定模型、尺寸与输出目录
+img-cli generate "a futuristic city at sunset" -m dall-e-3 -s 1792x1024 -q hd -o ~/Desktop
+
+# 指定输出格式为 JPEG
+img-cli generate "产品白底宣传图，极简风格" -m gpt-image-1 -q high --format jpeg -o ./output
+```
+
+### 2. 图片编辑 (edit)
+
+```bash
+# 本地图片全图编辑
+img-cli edit "给猫戴上一顶红色圣诞帽" --image ./cat.png -o ./output
+
+# 网络图片直接编辑
+img-cli edit "替换背景为星空" --image https://example.com/photo.jpg -o ./output
+
+# 带蒙版的局部编辑（蒙版透明区域为待修改区域）
+img-cli edit "用一朵玫瑰替换这里" --image ./photo.png --mask ./mask.png -o ./output
+```
+
+---
+
+## 命令参数参考
+
+### `img-cli generate <prompt>`
+
+| 参数 | 默认值 | 说明 |
+|---|---|---|
+| `prompt` | 必填 | 提示词（支持中文与英文） |
+| `-m`, `--model` | `gpt-image-2` | 模型名称（如 `gpt-image-2`, `dall-e-3`, `gpt-image-1`） |
+| `-s`, `--size` | `1024x1024` | 尺寸（如 `1024x1024`, `1536x1024`, `1024x1536`, `auto`） |
+| `-q`, `--quality` | 无 | 质量（`low` / `medium` / `high` / `auto` / `standard` / `hd`） |
+| `-n`, `--n` | `1` | 生成张数 |
+| `-o`, `--output` | `.` | 图片输出目录 |
+| `--format` | `png` | 输出格式：`png` / `jpeg` / `webp` |
+
+### `img-cli edit <prompt>`
+
+| 参数 | 默认值 | 说明 |
+|---|---|---|
+| `prompt` | 必填 | 修改描述 |
+| `-i`, `--image` | 必填 | 原图：本地路径或 HTTP/HTTPS URL |
+| `--mask` | 无 | 蒙版：本地路径或 URL（PNG 透明区域待修改） |
+| `-m`, `--model` | `gpt-image-2` | 模型名称 |
+| `-s`, `--size` | `auto` | 尺寸 |
+| `-q`, `--quality` | `auto` | 质量 |
+| `-n`, `--n` | `1` | 生成张数 |
+| `-o`, `--output` | `.` | 图片输出目录 |
+| `--format` | `png` | 输出格式：`png` / `jpeg` / `webp` |
+
+---
+
+## 运行测试
+
+```bash
+uv run pytest -v
+```

img_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+img_cli/__init__.py,sha256=vBugPxeKBKESQ9GPph61LPDDw7RdQ05XZ0v8Z11tcL8,405
+img_cli/_version.py,sha256=n_5vdJsPNu7wZ57LGuRL585uvll-hiuvZUBWzdG0RQU,520
+img_cli/cli.py,sha256=ej4rW3hF224tVVk6CYflyfY1EW-UE17_mYVNpvh9UaY,7963
+img_cli/client.py,sha256=af0RU21tXlQrkj5vrztTona1ktnajWqyX4jA0ie-Zfg,6227
+img_cli/config.py,sha256=a7M6U2Dk-5I9kUPA2Yq9cm87YaIW_lchCADcQTJdqZM,2350
+img_cli/image_utils.py,sha256=XPRcw55fe3byixDwxxeHYP9TcQ54S1UZHstywRXXd-E,5309
+img_cli/logger.py,sha256=InI38rc7PIJtPi7vQ76DF5yZ3uRzISuwO5jz4ghc4GA,2419
+img_cli-0.1.0.dist-info/METADATA,sha256=Y_BAsVTtPzahxFMFrt3DAzSrXUU9TDEnEilIbXJT0b0,4027
+img_cli-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+img_cli-0.1.0.dist-info/entry_points.txt,sha256=VRZPH6rNa4O0BkTUOmX2KcX6vHMi8Wj2mSKqhO5U4wE,45
+img_cli-0.1.0.dist-info/licenses/LICENSE,sha256=DWcolN0n9Am669uQA1E04dsdunFqNcqXk5YsOR8xS5o,1065
+img_cli-0.1.0.dist-info/RECORD,,

img_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

img_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+img-cli = img_cli.cli:main

img_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 8DE4732A
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.