Z-Image-Turbo Python API 调用示例详解

参数详解表

3. 解析返回值：输出路径、耗时与元数据

print(f"✅ 生成完成！共耗时：{gen_time:.2f} 秒")
print(f"📁 图像保存路径：{output_paths}")
print(f"📊 生成元数据：{metadata}")

返回值结构说明

示例元数据：

{
 "prompt": "一只可爱的橘色猫咪...",
 "negative_prompt": "低质量，模糊...",
 "width": 1024,
 "height": 1024,
 "steps": 40,
 "seed": 123456,
 "cfg": 7.5,
 "model": "Z-Image-Turbo-v1.0",
 "device": "cuda:0"
}

💡 实用建议：可将 metadata 保存至数据库或附加到图片 EXIF 中，便于后期追溯和版本管理。

实战案例：批量生成并自动分类存储

下面是一个典型的工程化应用场景——根据产品类别批量生成宣传图，并按目录归类。

完整代码实现

import os
import time
from app.core.generator import get_generator

# 初始化生成器
generator = get_generator()

# 定义产品类别与对应提示词模板
product_configs = [
    {
        "category": "coffee_cup",
        "prompt": "现代简约风格的白色陶瓷咖啡杯，放在木质桌面上，旁边有一本书和热咖啡，柔和光线，产品摄影",
        "size": (1024, 1024),
        "count": 3
    },
    {
        "category": "mountain_sunset",
        "prompt": "壮丽的山脉日出，云海翻腾，金色阳光洒在山峰上，油画风格，色彩鲜艳",
        "size": (1024, 576),
        "count": 2
    },
    {
        "category": "anime_girl",
        "prompt": "可爱的动漫少女，粉色长发，蓝色眼睛，穿着校服，樱花飘落，背景是教室",
        "size": (576, 1024),
        "count": 2
    }
]

# 批量生成主函数
def batch_generate():
    base_output_dir = "./outputs/batch/"
    os.makedirs(base_output_dir, exist_ok=True)
    results = []
    for config in product_configs:
        category = config["category"]
        prompt = config["prompt"]
        width, height = config["size"]
        num_images = config["count"]
        # 创建分类子目录
        category_dir = os.path.join(base_output_dir, category)
        os.makedirs(category_dir, exist_ok=True)
        print(f"\n🚀 开始生成 [{category}] 类别，共 {num_images} 张...")
        try:
            # 调用 API 生成图像
            output_paths, gen_time, metadata = generator.generate(
                prompt=prompt,
                negative_prompt="低质量，模糊，文字，水印",
                width=width,
                height=height,
                num_inference_steps=40,
                seed=-1, # 每次随机
                num_images=num_images,
                cfg_scale=7.5
            )
            # 移动文件到分类目录
            saved_paths = []
            for i, src_path in enumerate(output_paths):
                filename = f"{category}_{int(time.time())}_{i+1}.png"
                dst_path = os.path.join(category_dir, filename)
                os.rename(src_path, dst_path)
                saved_paths.append(dst_path)
            results.append({
                "category": category,
                "status": "success",
                "saved_paths": saved_paths,
                "time": gen_time,
                "metadata": metadata
            })
            print(f"✔️ [{category}] 生成成功，耗时 {gen_time:.2f}s")
        except Exception as e:
            results.append({
                "category": category,
                "status": "failed",
                "error": str(e)
            })
            print(f"❌ [{category}] 生成失败：{e}")
    return results

# 执行批量生成
if __name__ == "__main__":
    start_time = time.time()
    result_list = batch_generate()
    total_time = time.time() - start_time
    print(f"\n🎉 批量生成任务完成！总耗时：{total_time:.2f} 秒")
    for r in result_list:
        print(f" - {r['category']}: {r['status']}")

工程优化建议

高级技巧：自定义调度器与性能调优

虽然默认使用 DDPM/DDIM 调度器，但可通过内部接口替换更高效的采样策略。

示例：切换为 UniPC 加速采样器（支持 1~10 步高质量生成）

from diffsynth.pipeline import StableDiffusionPipeline
from diffsynth.schedulers import UniPCScheduler

# 获取原始 pipeline（需确保模型支持）
pipeline: StableDiffusionPipeline = generator.pipeline

# 替换调度器
pipeline.scheduler = UniPCScheduler.from_config(pipeline.scheduler.config)

# 启用极简生成模式
output_paths, gen_time, metadata = generator.generate(
    prompt="星空下的小屋，童话风格",
    width=768,
    height=768,
    num_inference_steps=8, # 仅需 8 步即可获得良好效果
    cfg_scale=6.0,
    num_images=1,
    seed=42
)
print(f"⚡ 使用 UniPC 仅用 {gen_time:.2f}s 完成生成！")

📌 适用场景：需要极速响应的服务端接口、移动端边缘计算等对延迟敏感的应用。

故障排查指南：常见问题与解决方案

最佳实践总结

1. 复用生成器实例：避免反复调用 get_generator()，应在应用启动时初始化一次。
2. 合理设置 CFG 值：日常使用推荐 7.0~9.0 区间，过高会导致颜色过饱和。
3. 控制并发数量：单卡建议并发不超过 2 个请求，防止显存溢出。
4. 启用日志记录：将每次调用参数与结果持久化，便于调试与审计。
5. 封装为服务层：建议将 API 调用封装成独立 Service 类，解耦业务逻辑。

总结：让 Z-Image-Turbo 真正服务于你的业务

本文详细解析了 Z-Image-Turbo Python API 的调用方式，从基础语法到工程实战，再到性能优化与故障处理，全面覆盖了二次开发所需的核心知识。

🔑 核心收获：

• 掌握 generate() 方法的完整参数体系
• 实现批量自动化生成与分类管理
• 理解底层架构，具备进一步定制能力
• 获得可直接投入生产的代码模板

通过合理利用该 API，你可以将 Z-Image-Turbo 深度集成进内容创作平台、电商平台、数字营销系统等各类应用场景，真正实现 AI 图像生产力升级。