ai-image-client
AI 图像生成客户端库，支持多种模型，提供统一的图像生成接口。
目前支持
GPT-IMAGE-2和NanoBanana（Gemini）两种模型，均支持文本生成图像（txt2img）和图像编辑（img2img）两种模式。
安装
pip install ai-image-client
使用示例
GPT-IMAGE-2
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 数据，以及它们的列表。
# 方式一：传入 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）
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())
图像编辑（传入参考图）
# 传入 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() 获取错误信息。
1 maintainer
Metadata
1 maintainer
Release files for ai-image-client 0.1.5
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
Total release size: 6.5 MB
Release files / ai_image_client-0.1.5-cp314-cp314-win_amd64.whl
| Download URL | ai_image_client-0.1.5-cp314-cp314-win_amd64.whl |
|---|---|
| Size | 122.4 kB |
| Tags | CPython 3.14 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
287bf39f88fc6d6321b2cfed40eb28bfcaac47e1f90dbd948740f806ef83a621
|
|
BLAKE2b-256 checksum How to use checksums |
edf75acad956862f1fb55d3311a75ebd282b4753db17972e2b21713748845838
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 25, 2026.
Transparency logRelease files / ai_image_client-0.1.5-cp314-cp314-manylinux_2_17_x86_64.whl
| Download URL | ai_image_client-0.1.5-cp314-cp314-manylinux_2_17_x86_64.whl |
|---|---|
| Size | 826.2 kB |
| Tags | CPython 3.14 Linux glibc 2.17+ x86-64 |
|
SHA-256 checksum How to use checksums |
c768deb0a116e8a2e349062a7826654cd1e98947e1c7926dd80fc5c69e91dce9
|
|
BLAKE2b-256 checksum How to use checksums |
7806b2134a4241e78849c994a6f409b27a7e52c86e8bfd1e1dfb4777e967fb77
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 25, 2026.
Transparency logRelease files / ai_image_client-0.1.5-cp313-cp313-win_amd64.whl
| Download URL | ai_image_client-0.1.5-cp313-cp313-win_amd64.whl |
|---|---|
| Size | 120.1 kB |
| Tags | CPython 3.13 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
b7eb8f9831c78bfc778827f947b79c16eace02dd2e66474c381d4a9e1a0f19e9
|
|
BLAKE2b-256 checksum How to use checksums |
0c0378bcf49b1d4339896028d032006d25c18c1e1d8b1b6b0e0cc6e76adbbcfe
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 25, 2026.
Transparency logRelease files / ai_image_client-0.1.5-cp313-cp313-manylinux_2_17_x86_64.whl
| Download URL | ai_image_client-0.1.5-cp313-cp313-manylinux_2_17_x86_64.whl |
|---|---|
| Size | 833.9 kB |
| Tags | CPython 3.13 Linux glibc 2.17+ x86-64 |
|
SHA-256 checksum How to use checksums |
b63ab3866a1f8bef218895cf57d1d3636b017ef6deac9b2dc09d1ddd0da4df9a
|
|
BLAKE2b-256 checksum How to use checksums |
fa3069717e3e7a6bf2ae2a28689876be6977ab8b67e19b481f33c03d5334abf4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 25, 2026.
Transparency logRelease files / ai_image_client-0.1.5-cp312-cp312-win_amd64.whl
| Download URL | ai_image_client-0.1.5-cp312-cp312-win_amd64.whl |
|---|---|
| Size | 121.4 kB |
| Tags | CPython 3.12 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
1fc5132e99f3681e4d5c7050ce97eebd4bd25e20513a03ad94e0aebdf5bfd617
|
|
BLAKE2b-256 checksum How to use checksums |
550062115ab5428309a2b6173a718f51cb135950b8664594b10d978363bb3148
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 25, 2026.
Transparency logRelease files / ai_image_client-0.1.5-cp312-cp312-manylinux_2_17_x86_64.whl
| Download URL | ai_image_client-0.1.5-cp312-cp312-manylinux_2_17_x86_64.whl |
|---|---|
| Size | 836.2 kB |
| Tags | CPython 3.12 Linux glibc 2.17+ x86-64 |
|
SHA-256 checksum How to use checksums |
06b447f0b7448456da0a89892f95cc0f8f9e540f3753f1e3cef7b4835088b40e
|
|
BLAKE2b-256 checksum How to use checksums |
10126ad15bf81e39af35be194d0b1b27a121a6c3423996b48e8f9f2056b706df
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 25, 2026.
Transparency logRelease files / ai_image_client-0.1.5-cp311-cp311-win_amd64.whl
| Download URL | ai_image_client-0.1.5-cp311-cp311-win_amd64.whl |
|---|---|
| Size | 124.2 kB |
| Tags | CPython 3.11 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
56e43b0dba6e485fd819311fb070b2d05da168c4c1bb4ab58585c98ba0ca6eeb
|
|
BLAKE2b-256 checksum How to use checksums |
90b60409dd801e8aa1efbc85dbd17b3d4c4e1395156bcee3cde6e1cf4d111f7c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 25, 2026.
Transparency logRelease files / ai_image_client-0.1.5-cp311-cp311-manylinux_2_17_x86_64.whl
| Download URL | ai_image_client-0.1.5-cp311-cp311-manylinux_2_17_x86_64.whl |
|---|---|
| Size | 809.4 kB |
| Tags | CPython 3.11 Linux glibc 2.17+ x86-64 |
|
SHA-256 checksum How to use checksums |
9039d90338c8ae738692ca4074c653bb516a0b66106c39c174da6ec2c51a58fe
|
|
BLAKE2b-256 checksum How to use checksums |
1017ec22d390b31071e853c7ab1f7d67e78eeae7d9b7e0b1c490ebeca266fa6d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 25, 2026.
Transparency logRelease files / ai_image_client-0.1.5-cp310-cp310-win_amd64.whl
| Download URL | ai_image_client-0.1.5-cp310-cp310-win_amd64.whl |
|---|---|
| Size | 124.1 kB |
| Tags | CPython 3.10 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
11ad73ecfd5044e098d23bb4a5988190c3b0b5a6e7ca7095d832545c1b1d5ef7
|
|
BLAKE2b-256 checksum How to use checksums |
632e295b55852e328d34acea0a9ea12d5b14c1f3b3b747fb9e7095783ba65e6a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 25, 2026.
Transparency logRelease files / ai_image_client-0.1.5-cp310-cp310-manylinux_2_17_x86_64.whl
| Download URL | ai_image_client-0.1.5-cp310-cp310-manylinux_2_17_x86_64.whl |
|---|---|
| Size | 776.5 kB |
| Tags | CPython 3.10 Linux glibc 2.17+ x86-64 |
|
SHA-256 checksum How to use checksums |
dfc071b095f94bae6b9a7d204d3b95c7f807c20c53791021000173a6b03784b8
|
|
BLAKE2b-256 checksum How to use checksums |
252f07c2a13f9ea3aa770c5a705dcaed4883e1a244ce0c0a6223f68c7d137269
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 25, 2026.
Transparency logRelease files / ai_image_client-0.1.5-cp39-cp39-win_amd64.whl
| Download URL | ai_image_client-0.1.5-cp39-cp39-win_amd64.whl |
|---|---|
| Size | 124.3 kB |
| Tags | CPython 3.9 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
54b359754a241ca80847e715932ce984188d61e38f3d10b52f87293ee0e38d8c
|
|
BLAKE2b-256 checksum How to use checksums |
0835f77fa87247cdec7a7afb8e51b02ec4253da3431622ea4cb3f30a4e0decb8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 25, 2026.
Transparency logRelease files / ai_image_client-0.1.5-cp39-cp39-manylinux_2_17_x86_64.whl
| Download URL | ai_image_client-0.1.5-cp39-cp39-manylinux_2_17_x86_64.whl |
|---|---|
| Size | 771.0 kB |
| Tags | CPython 3.9 Linux glibc 2.17+ x86-64 |
|
SHA-256 checksum How to use checksums |
c1b85ed6194518033c760c1b42b9325d7d0866b1b33827d14464e9eeae34f903
|
|
BLAKE2b-256 checksum How to use checksums |
0f2a4a1a88c69d8a6d073a8b27fadf1f4fcbd72d5484409704a53f8b9968dd4f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 25, 2026.
Transparency logRelease files / ai_image_client-0.1.5-cp38-cp38-win_amd64.whl
| Download URL | ai_image_client-0.1.5-cp38-cp38-win_amd64.whl |
|---|---|
| Size | 127.5 kB |
| Tags | CPython 3.8 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
9207b42fef179197d04c64219618dee7c1d18021e30f5a273cfa97e325310cac
|
|
BLAKE2b-256 checksum How to use checksums |
0518a5f237ffb10c9227eafa563dde0fe6d81a69347668598a5ba7cd80988fad
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 25, 2026.
Transparency logRelease files / ai_image_client-0.1.5-cp38-cp38-manylinux_2_17_x86_64.whl
| Download URL | ai_image_client-0.1.5-cp38-cp38-manylinux_2_17_x86_64.whl |
|---|---|
| Size | 817.4 kB |
| Tags | CPython 3.8 Linux glibc 2.17+ x86-64 |
|
SHA-256 checksum How to use checksums |
304ce9cf4874647dcf6954d89861e5b2d6eec8059a42dcbf95c0bcc5ffc35305
|
|
BLAKE2b-256 checksum How to use checksums |
4f93f1252534047046df454c66ddaf04c15766d6ad4a64ef057633b94f00792b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 25, 2026.
Transparency log
