Metadata-Version: 2.1
Name: ai_image_client
Version: 0.1.5
Summary: AI 图像生成客户端库
Home-page: https://github.com/zhenzi0322-package/ai-image-client
Author: zhenzi0322
Author-email: zhenzi0322 <82131529@qq.com>
License: MIT
Requires-Python: >=3.8
description-content-type: text/markdown
Description:
 
 <p align="center">
   <h1>ai-image-client</h1>
   <a href="https://pypi.org/project/ai-image-client/"><img src="https://img.shields.io/pypi/v/ai-image-client.svg" alt="PyPI version"></a>
   <a href="https://pypi.org/project/ai-image-client/"><img src="https://img.shields.io/badge/Python-3.8~3.14-3776AB?logo=python&logoColor=white" alt="Python"></a>
   <a href="https://github.com/zhenzi0322-package/ai-image-client/blob/master/LICENSE"><img src="https://img.shields.io/pypi/l/py2pydso.svg" alt="License"></a>
   <a href="https://tool.long920.cn/ai-image-client"><img src="https://app.readthedocs.org/projects/zhenzi0322-tool/badge/?version=latest" alt="Documentation Status"></a>
 </p>
 
 > AI 图像生成客户端库，支持多种模型，提供统一的图像生成接口。
 > 
 > 目前支持`GPT-IMAGE-2`和`NanoBanana（Gemini）`两种模型，均支持文本生成图像（`txt2img`）和图像编辑（`img2img`）两种模式。
 
 ---
 
 
 ## 安装
 
 ```bash
 pip install ai-image-client
 ```
 
 
 ## 使用示例
 
 ### GPT-IMAGE-2
 
 ```python
 from ai_image_client import GPTImage2Client
 
 # 初始化客户端
 client = GPTImage2Client(
     base_url="https://your-api-host.com",
     token="your-api-token",
 )
 
 # 文本生成图像
 result = client.start(
     prompt="一只可爱的猫咪，水彩画风格",
     aspect_ratio="1:1",
     quality="high",
     image_size="1k",
     task_id="task_001",
     model_key="gpt-image-2",
 )
 
 if result.is_success:
     image_bytes = result.data  # 图像二进制数据
     with open('images/result.png', 'wb') as fp:
         fp.write(image_bytes)
 else:
     print(result.to_dict())
 ```
 
 ### 图像编辑（传入参考图）
 
 `files` 参数支持多种输入格式：HTTP 链接、本地文件路径、bytes 数据，以及它们的列表。
 
 ```python
 # 方式一：传入 HTTP 图片链接
 result = client.start(
     prompt="将背景替换为星空",
     aspect_ratio="1:1",
     quality="medium",
     files="https://example.com/reference.png",
     task_id="task_002",
     model_key="gpt-image-2",
 )
 
 # 方式二：传入本地文件路径
 result = client.start(
     prompt="将背景替换为星空",
     files="/path/to/reference.png",
     task_id="task_003",
     model_key="gpt-image-2",
 )
 
 # 方式三：传入 bytes 数据
 with open("reference.png", "rb") as f:
     result = client.start(
         prompt="将背景替换为星空",
         files=f.read(),
         task_id="task_004",
         model_key="gpt-image-2",
     )
 
 # 方式四：传入混合列表（URL + 路径 + bytes 均可混合）
 result = client.start(
     prompt="合成两张图片",
     files=[
         "https://example.com/img1.png",
         "/path/to/img2.png",
     ],
     task_id="task_005",
     model_key="gpt-image-2",
 )
 ```
 
 ### NanoBanana（Gemini）
 
 ```python
 from ai_image_client import NanoBananaClient
 
 # 初始化客户端
 client = NanoBananaClient(
     base_url="https://your-api-host.com",
     api_key="your-api-token",
 )
 
 # 文本生成图像
 result = client.start(
     prompt="一只可爱的猫咪，水彩画风格",
     aspect_ratio="2:3",
     image_size="1K",
     task_id="task_001",
     model_key="nanobanan",
 )
 
 if result.is_success:
     image_bytes = result.data
     with open('images/result.png', 'wb') as fp:
         fp.write(image_bytes)
 else:
     print(result.to_dict())
 ```
 
 #### 图像编辑（传入参考图）
 
 ```python
 # 传入 HTTP 链接
 result = client.start(
     prompt="将背景替换为星空",
     aspect_ratio="2:3",
     files="https://example.com/reference.png",
     task_id="task_002",
     model_key="nanobanan",
 )
 
 # 传入本地文件路径
 result = client.start(
     prompt="将背景替换为星空",
     files="/path/to/reference.png",
     task_id="task_003",
     model_key="nanobanan",
 )
 
 # 传入混合列表
 result = client.start(
     prompt="合成两张图片",
     files=[
         "https://example.com/img1.png",
         "/path/to/img2.png",
     ],
     task_id="task_004",
     model_key="nanobanan",
 )
 ```
 
 
 ## API 说明
 
 ### GPTImage2Client
 
 | 参数 | 类型 | 说明 |
 |------|------|------|
 | `base_url` | `str` | API 服务地址 |
 | `token` | `str` | API 鉴权 Token |
 | `model_tag` | `str` | 模型标识标签，默认 `GPT-IMAGE-2` |
 | `logger` | `logging.Logger` | 自定义日志器 |
 
 ### start()
 
 | 参数 | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
 | `prompt` | `str` | 必填 | 图像生成描述 |
 | `aspect_ratio` | `str` | `''` | 宽高比，如 `1:1`、`16:9`，空则自动 |
 | `quality` | `str` | `''` | 画质：`low` / `medium` / `high` |
 | `image_size` | `str` | `''` | 分辨率：`1k`、`2k`、`4k` |
 | `files` | `Union[List[bytes], bytes, str, List[str]]` | `None` | 参考图像，支持 HTTP 链接 / 本地路径 / bytes / 混合列表 |
 | `task_id` | `str` | — | 自定义任务 ID（通过 kwargs 传入） |
 | `model_key` | `str` | — | 自定义模型 Key（通过 kwargs 传入） |
 | `response_format` | `str` | `b64_json` | 通过 `kwargs` 传入。可选`b64_json`或`url` |
 | `model` | `str` | `gpt-image-2` | 调用的模型。通过 `kwargs` 传入。 |
 | `timeout` | `int` | `http_client.base_timeout` | 超时时间（通过 kwargs 传入），未传时使用 `config.py` 中的 `base_timeout` |
 
 **返回值：** `ServiceResult` — 成功时 `result.data` 为图像 `bytes`，失败时通过 `result.to_dict()` 获取错误信息。
 
 ### NanoBananaClient
 
 | 参数 | 类型 | 说明 |
 |------|------|------|
 | `base_url` | `str` | API 服务地址 |
 | `api_key` | `str` | API 鉴权 Token |
 | `model_tag` | `str` | 模型标识标签，默认 `NANOBANAN` |
 | `logger` | `logging.Logger` | 自定义日志器 |
 
 ### start()
 
 | 参数 | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
 | `prompt` | `str` | 必填 | 图像生成描述 |
 | `aspect_ratio` | `str` | `'2:3'` | 宽高比，可选：`1:1` / `2:3` / `3:2` / `3:4` / `4:3` / `4:5` / `5:4` / `9:16` / `16:9` / `21:9` |
 | `image_size` | `str` | `'1K'` | 分辨率：`1K`、`2K`、`4K` |
 | `model` | `str` | `'gemini-3-pro-image-preview'` | 调用的模型，可选：`gemini-3-pro-image-preview` / `gemini-3.1-flash-image-preview` / `gemini-2.5-flash-image` |
 | `files` | `Union[List[bytes], bytes, str, List[str]]` | `None` | 参考图像，支持 HTTP 链接 / 本地路径 / bytes / 混合列表 |
 | `task_id` | `str` | — | 自定义任务 ID（通过 kwargs 传入） |
 | `model_key` | `str` | — | 自定义模型 Key（通过 kwargs 传入） |
 | `timeout` | `int` | `http_client.base_timeout` | 超时时间（通过 kwargs 传入），未传时使用 `config.py` 中的 `base_timeout` |
 
 **返回值：** `ServiceResult` — 成功时 `result.data` 为图像 `bytes`，失败时通过 `result.to_dict()` 获取错误信息。
 
 
Requires-Dist: excode
Requires-Dist: pixlib
Requires-Dist: imgnorm
