ai-image-client

PyPI version Python License Documentation Status

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() 获取错误信息。

Project links

Data verified by PyPI on
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for zhenzi0322 from gravatar.com zhenzi0322

Credits

PyPI data
Data sourced directly from PyPI's database.

Author: zhenzi0322

GitHub Statistics

Data verified by PyPI on 
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT

Requires

Python >=3.8

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

ai_image_client-0.1.5-cp314-cp314-win_amd64.whl (122.4 kB view details)

Uploaded CPython 3.14Windows x86-64

ai_image_client-0.1.5-cp314-cp314-manylinux_2_17_x86_64.whl (826.2 kB view details)

Uploaded CPython 3.14manylinux: glibc 2.17+ x86-64

ai_image_client-0.1.5-cp313-cp313-win_amd64.whl (120.1 kB view details)

Uploaded CPython 3.13Windows x86-64

ai_image_client-0.1.5-cp313-cp313-manylinux_2_17_x86_64.whl (833.9 kB view details)

Uploaded CPython 3.13manylinux: glibc 2.17+ x86-64

ai_image_client-0.1.5-cp312-cp312-win_amd64.whl (121.4 kB view details)

Uploaded CPython 3.12Windows x86-64

ai_image_client-0.1.5-cp312-cp312-manylinux_2_17_x86_64.whl (836.2 kB view details)

Uploaded CPython 3.12manylinux: glibc 2.17+ x86-64

ai_image_client-0.1.5-cp311-cp311-win_amd64.whl (124.2 kB view details)

Uploaded CPython 3.11Windows x86-64

ai_image_client-0.1.5-cp311-cp311-manylinux_2_17_x86_64.whl (809.4 kB view details)

Uploaded CPython 3.11manylinux: glibc 2.17+ x86-64

ai_image_client-0.1.5-cp310-cp310-win_amd64.whl (124.1 kB view details)

Uploaded CPython 3.10Windows x86-64

ai_image_client-0.1.5-cp310-cp310-manylinux_2_17_x86_64.whl (776.5 kB view details)

Uploaded CPython 3.10manylinux: glibc 2.17+ x86-64

ai_image_client-0.1.5-cp39-cp39-win_amd64.whl (124.3 kB view details)

Uploaded CPython 3.9Windows x86-64

ai_image_client-0.1.5-cp39-cp39-manylinux_2_17_x86_64.whl (771.0 kB view details)

Uploaded CPython 3.9manylinux: glibc 2.17+ x86-64

ai_image_client-0.1.5-cp38-cp38-win_amd64.whl (127.5 kB view details)

Uploaded CPython 3.8Windows x86-64

ai_image_client-0.1.5-cp38-cp38-manylinux_2_17_x86_64.whl (817.4 kB view details)

Uploaded CPython 3.8manylinux: glibc 2.17+ x86-64

File details

Details for the file ai_image_client-0.1.5-cp314-cp314-win_amd64.whl.

File metadata

File hashes

Hashes for ai_image_client-0.1.5-cp314-cp314-win_amd64.whl
Algorithm Hash digest
SHA256 287bf39f88fc6d6321b2cfed40eb28bfcaac47e1f90dbd948740f806ef83a621
MD5 747c182598a8f44824d74499a480fe30
BLAKE2b-256 edf75acad956862f1fb55d3311a75ebd282b4753db17972e2b21713748845838

See more details on using hashes here.

Provenance

The following attestation bundles were made for ai_image_client-0.1.5-cp314-cp314-win_amd64.whl:

Publisher: wheels.yml on zhenzi0322-package/ai-image-client

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file ai_image_client-0.1.5-cp314-cp314-manylinux_2_17_x86_64.whl.

File metadata

File hashes

Hashes for ai_image_client-0.1.5-cp314-cp314-manylinux_2_17_x86_64.whl
Algorithm Hash digest
SHA256 c768deb0a116e8a2e349062a7826654cd1e98947e1c7926dd80fc5c69e91dce9
MD5 09a020baa429f12b2321ffb5a7584c79
BLAKE2b-256 7806b2134a4241e78849c994a6f409b27a7e52c86e8bfd1e1dfb4777e967fb77

See more details on using hashes here.

Provenance

The following attestation bundles were made for ai_image_client-0.1.5-cp314-cp314-manylinux_2_17_x86_64.whl:

Publisher: wheels.yml on zhenzi0322-package/ai-image-client

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file ai_image_client-0.1.5-cp313-cp313-win_amd64.whl.

File metadata

File hashes

Hashes for ai_image_client-0.1.5-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 b7eb8f9831c78bfc778827f947b79c16eace02dd2e66474c381d4a9e1a0f19e9
MD5 437e147cd00c237f3b1f31040ff0b321
BLAKE2b-256 0c0378bcf49b1d4339896028d032006d25c18c1e1d8b1b6b0e0cc6e76adbbcfe

See more details on using hashes here.

Provenance

The following attestation bundles were made for ai_image_client-0.1.5-cp313-cp313-win_amd64.whl:

Publisher: wheels.yml on zhenzi0322-package/ai-image-client

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file ai_image_client-0.1.5-cp313-cp313-manylinux_2_17_x86_64.whl.

File metadata

File hashes

Hashes for ai_image_client-0.1.5-cp313-cp313-manylinux_2_17_x86_64.whl
Algorithm Hash digest
SHA256 b63ab3866a1f8bef218895cf57d1d3636b017ef6deac9b2dc09d1ddd0da4df9a
MD5 731662fd5b3a6ed2c1748f657441b4f7
BLAKE2b-256 fa3069717e3e7a6bf2ae2a28689876be6977ab8b67e19b481f33c03d5334abf4

See more details on using hashes here.

Provenance

The following attestation bundles were made for ai_image_client-0.1.5-cp313-cp313-manylinux_2_17_x86_64.whl:

Publisher: wheels.yml on zhenzi0322-package/ai-image-client

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file ai_image_client-0.1.5-cp312-cp312-win_amd64.whl.

File metadata

File hashes

Hashes for ai_image_client-0.1.5-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 1fc5132e99f3681e4d5c7050ce97eebd4bd25e20513a03ad94e0aebdf5bfd617
MD5 64e961c80cd9cb7e1386ccfba419895d
BLAKE2b-256 550062115ab5428309a2b6173a718f51cb135950b8664594b10d978363bb3148

See more details on using hashes here.

Provenance

The following attestation bundles were made for ai_image_client-0.1.5-cp312-cp312-win_amd64.whl:

Publisher: wheels.yml on zhenzi0322-package/ai-image-client

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file ai_image_client-0.1.5-cp312-cp312-manylinux_2_17_x86_64.whl.

File metadata

File hashes

Hashes for ai_image_client-0.1.5-cp312-cp312-manylinux_2_17_x86_64.whl
Algorithm Hash digest
SHA256 06b447f0b7448456da0a89892f95cc0f8f9e540f3753f1e3cef7b4835088b40e
MD5 9ae0f7f4024d131e1d4d4d3653358d17
BLAKE2b-256 10126ad15bf81e39af35be194d0b1b27a121a6c3423996b48e8f9f2056b706df

See more details on using hashes here.

Provenance

The following attestation bundles were made for ai_image_client-0.1.5-cp312-cp312-manylinux_2_17_x86_64.whl:

Publisher: wheels.yml on zhenzi0322-package/ai-image-client

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file ai_image_client-0.1.5-cp311-cp311-win_amd64.whl.

File metadata

File hashes

Hashes for ai_image_client-0.1.5-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 56e43b0dba6e485fd819311fb070b2d05da168c4c1bb4ab58585c98ba0ca6eeb
MD5 053fe27d8ef6f7bcdac6f8f28111fc15
BLAKE2b-256 90b60409dd801e8aa1efbc85dbd17b3d4c4e1395156bcee3cde6e1cf4d111f7c

See more details on using hashes here.

Provenance

The following attestation bundles were made for ai_image_client-0.1.5-cp311-cp311-win_amd64.whl:

Publisher: wheels.yml on zhenzi0322-package/ai-image-client

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file ai_image_client-0.1.5-cp311-cp311-manylinux_2_17_x86_64.whl.

File metadata

File hashes

Hashes for ai_image_client-0.1.5-cp311-cp311-manylinux_2_17_x86_64.whl
Algorithm Hash digest
SHA256 9039d90338c8ae738692ca4074c653bb516a0b66106c39c174da6ec2c51a58fe
MD5 60a2dba62fcc9549dced05bc8128f5d8
BLAKE2b-256 1017ec22d390b31071e853c7ab1f7d67e78eeae7d9b7e0b1c490ebeca266fa6d

See more details on using hashes here.

Provenance

The following attestation bundles were made for ai_image_client-0.1.5-cp311-cp311-manylinux_2_17_x86_64.whl:

Publisher: wheels.yml on zhenzi0322-package/ai-image-client

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file ai_image_client-0.1.5-cp310-cp310-win_amd64.whl.

File metadata

File hashes

Hashes for ai_image_client-0.1.5-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 11ad73ecfd5044e098d23bb4a5988190c3b0b5a6e7ca7095d832545c1b1d5ef7
MD5 20e372dacb10aab3e84e9964756f7f63
BLAKE2b-256 632e295b55852e328d34acea0a9ea12d5b14c1f3b3b747fb9e7095783ba65e6a

See more details on using hashes here.

Provenance

The following attestation bundles were made for ai_image_client-0.1.5-cp310-cp310-win_amd64.whl:

Publisher: wheels.yml on zhenzi0322-package/ai-image-client

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file ai_image_client-0.1.5-cp310-cp310-manylinux_2_17_x86_64.whl.

File metadata

File hashes

Hashes for ai_image_client-0.1.5-cp310-cp310-manylinux_2_17_x86_64.whl
Algorithm Hash digest
SHA256 dfc071b095f94bae6b9a7d204d3b95c7f807c20c53791021000173a6b03784b8
MD5 f75cbdf4fd8cf9c115c4f8ee2d3a4e58
BLAKE2b-256 252f07c2a13f9ea3aa770c5a705dcaed4883e1a244ce0c0a6223f68c7d137269

See more details on using hashes here.

Provenance

The following attestation bundles were made for ai_image_client-0.1.5-cp310-cp310-manylinux_2_17_x86_64.whl:

Publisher: wheels.yml on zhenzi0322-package/ai-image-client

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file ai_image_client-0.1.5-cp39-cp39-win_amd64.whl.

File metadata

File hashes

Hashes for ai_image_client-0.1.5-cp39-cp39-win_amd64.whl
Algorithm Hash digest
SHA256 54b359754a241ca80847e715932ce984188d61e38f3d10b52f87293ee0e38d8c
MD5 bd526db72538d82fb8beb48efe4e5dca
BLAKE2b-256 0835f77fa87247cdec7a7afb8e51b02ec4253da3431622ea4cb3f30a4e0decb8

See more details on using hashes here.

Provenance

The following attestation bundles were made for ai_image_client-0.1.5-cp39-cp39-win_amd64.whl:

Publisher: wheels.yml on zhenzi0322-package/ai-image-client

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file ai_image_client-0.1.5-cp39-cp39-manylinux_2_17_x86_64.whl.

File metadata

File hashes

Hashes for ai_image_client-0.1.5-cp39-cp39-manylinux_2_17_x86_64.whl
Algorithm Hash digest
SHA256 c1b85ed6194518033c760c1b42b9325d7d0866b1b33827d14464e9eeae34f903
MD5 8f9f11e4a6fc7b6e14245ed8c62743e0
BLAKE2b-256 0f2a4a1a88c69d8a6d073a8b27fadf1f4fcbd72d5484409704a53f8b9968dd4f

See more details on using hashes here.

Provenance

The following attestation bundles were made for ai_image_client-0.1.5-cp39-cp39-manylinux_2_17_x86_64.whl:

Publisher: wheels.yml on zhenzi0322-package/ai-image-client

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file ai_image_client-0.1.5-cp38-cp38-win_amd64.whl.

File metadata

File hashes

Hashes for ai_image_client-0.1.5-cp38-cp38-win_amd64.whl
Algorithm Hash digest
SHA256 9207b42fef179197d04c64219618dee7c1d18021e30f5a273cfa97e325310cac
MD5 0a3ec3ea6469b5a543a7569a27ccb4af
BLAKE2b-256 0518a5f237ffb10c9227eafa563dde0fe6d81a69347668598a5ba7cd80988fad

See more details on using hashes here.

Provenance

The following attestation bundles were made for ai_image_client-0.1.5-cp38-cp38-win_amd64.whl:

Publisher: wheels.yml on zhenzi0322-package/ai-image-client

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file ai_image_client-0.1.5-cp38-cp38-manylinux_2_17_x86_64.whl.

File metadata

File hashes

Hashes for ai_image_client-0.1.5-cp38-cp38-manylinux_2_17_x86_64.whl
Algorithm Hash digest
SHA256 304ce9cf4874647dcf6954d89861e5b2d6eec8059a42dcbf95c0bcc5ffc35305
MD5 70c68f6149dfac04e6f0d63aacbb37e1
BLAKE2b-256 4f93f1252534047046df454c66ddaf04c15766d6ad4a64ef057633b94f00792b

See more details on using hashes here.

Provenance

The following attestation bundles were made for ai_image_client-0.1.5-cp38-cp38-manylinux_2_17_x86_64.whl:

Publisher: wheels.yml on zhenzi0322-package/ai-image-client

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page