Z Image Turbo 快速入门：使用 LoRA 实现快速文生图

Z Image Turbo 在 Novita AI 上通过两个异步端点提供：POST https://api.novita.ai/v3/async/z-image-turbo 用于标准文生图生成，以及 POST https://api.novita.ai/v3/async/z-image-turbo-lora 用于结合 LoRA 风格模型的生成。两者都遵循 Novita AI 的标准异步模式——提交请求，接收 task_id，然后轮询 GET /v3/async/task-result 直到图像就绪。本指南将端到端地介绍这两个端点：首次请求、轮询循环、LoRA 使用，以及在生产代码之前需要查阅的参数参考。

何时使用本快速入门指南

当您需要在添加错误处理、批处理或生产逻辑之前，获得一个经过验证的 Z Image Turbo 工作请求时，请使用本指南。

Z Image Turbo 专为高吞吐量而设计。它适用于以下工作流程：

• 速度比最高质量更重要——原型管线、批量预览生成，或延迟是硬性约束的实时应用。
• 您希望使用基于 LoRA 的风格迁移，而无需配置完整的 txt2img 参数集。专用的 LoRA 端点接受 loras 数组，并处理其余部分。
• 您需要一个简单的“提示词输入 / 图像输出”接口，且请求体尽可能精简。

当您需要完整的 Stable Diffusion 配置表面时——例如 steps、guidance_scale、sampler_name、negative_prompt、hires_fix、精炼模型等——Z Image Turbo 就不是合适的选择。如需那种级别的控制，请使用标准的 POST /v3/async/txt2img 端点。

本指南仅涵盖 Novita AI 托管的 API 路径。它不涉及自托管或微调。

步骤 1：获取您的 Novita API 密钥

创建一个 Novita AI 账户，并导航到 API 密钥管理 页面。生成一个密钥并导出：

export NOVITA_API_KEY="your_api_key_here"

请将密钥妥善保管，不要将其放入版本控制、客户端代码包或 Docker 镜像层中。

步骤 2：确认端点

Novita AI 上的 Z Image Turbo 使用两个独立的提交端点和一个共享的结果端点：

	基础 T2I	LoRA T2I
提交	POST https://api.novita.ai/v3/async/z-image-turbo	POST https://api.novita.ai/v3/async/z-image-turbo-lora
结果轮询	GET https://api.novita.ai/v3/async/task-result?task_id=<id>	GET https://api.novita.ai/v3/async/task-result?task_id=<id>
API 参考	Z Image Turbo 文档	Z Image Turbo LoRA 文档

两个提交端点都只返回一个 task_id。结果轮询端点对两者完全相同——一旦您的轮询循环适用于其中一个，也就适用于另一个。

步骤 3：发送您的第一个请求

基础端点需要 prompt 和 size。在添加可选参数之前，请从这里开始：

curl -s -X POST https://api.novita.ai/v3/async/z-image-turbo \
  -H "Authorization: Bearer $NOVITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A futuristic city skyline at dusk, neon lights, photorealistic, ultra-detailed",
    "size": "1024*1024"
  }'

成功的 200 响应会返回：

{
  "task_id": "abc123..."
}

保存 task_id。提交时不会返回其他内容——生成是异步运行的。

基础端点上有两个可选参数：

• seed（整数）：用于固定可复现输出的种子。相同的提示词和种子组合将返回一致的结果。
• enable_base64_output（布尔值）：当为 true 时，结果将包含图像的 base64 编码字符串，而不是托管 URL。

步骤 4：轮询获取结果

使用 task_id 作为查询参数，GET 请求任务结果端点：

curl -s "https://api.novita.ai/v3/async/task-result?task_id=abc123..." \
  -H "Authorization: Bearer $NOVITA_API_KEY"

已完成的任务返回：

{
  "task": {
    "task_id": "abc123...",
    "status": "TASK_STATUS_SUCCEED",
    "progress_percent": 100,
    "eta": 0
  },
  "images": [
    {
      "image_url": "https://...",
      "image_url_ttl": 3600,
      "image_type": "png"
    }
  ]
}

每 1-2 秒轮询一次，直到 task.status 变为 TASK_STATUS_SUCCEED 或 TASK_STATUS_FAILED。当任务仍在队列中时，task.eta 字段提供估计的剩余秒数。

image_url_ttl 是 URL 的生命周期（以秒计）。请在 TTL 过期前下载并存储图像——托管 URL 不是永久有效的。

步骤 5：查看定价、限制和常见错误

Z Image Turbo 的当前定价列在 Novita AI 定价页面 和 Z Image Turbo 模型页面 上。在制定成本估算前，请核实费率，因为定价可能会发生变化。

常见错误：

错误	原因	修复
401 Unauthorized	API 密钥缺失或格式错误	确认请求头格式为 Authorization: Bearer <key>
400 Bad Request	请求体无效	确认 prompt 和 size 为字符串；如果提供了 seed，它必须是整数
TASK_STATUS_FAILED	生成被拒绝或出错	读取结果响应中的 task.reason 以获取具体的失败信息
图像 URL 返回 403 或已过期	在 TTL 过期后访问 URL	在 image_url_ttl 秒内下载并存储图像

Python 示例

完整工作流程——提交、轮询、返回图像 URL：

import os
import time
import requests

API_KEY = os.environ["NOVITA_API_KEY"]
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

def generate_image(prompt: str, size: str = "1024*1024", seed: int = None) -> str:
    payload = {"prompt": prompt, "size": size}
    if seed is not None:
        payload["seed"] = seed

    resp = requests.post(
        "https://api.novita.ai/v3/async/z-image-turbo",
        json=payload,
        headers=HEADERS,
    )
    resp.raise_for_status()
    task_id = resp.json()["task_id"]

    while True:
        result = requests.get(
            f"https://api.novita.ai/v3/async/task-result?task_id={task_id}",
            headers=HEADERS,
        )
        result.raise_for_status()
        data = result.json()
        status = data["task"]["status"]

        if status == "TASK_STATUS_SUCCEED":
            return data["images"][0]["image_url"]
        if status == "TASK_STATUS_FAILED":
            raise RuntimeError(f"Generation failed: {data['task'].get('reason', 'unknown')}")

        time.sleep(1)

if __name__ == "__main__":
    url = generate_image(
        "A futuristic city skyline at dusk, neon lights, photorealistic",
        size="1024*1024",
        seed=42,
    )
    print(url)

LoRA 生成

LoRA 端点在请求中增加了一个 loras 数组。每个条目包含一个 path（来自 Novita AI 模型中心的 LoRA 模型标识符）和一个 scale（影响权重）：

curl -s -X POST https://api.novita.ai/v3/async/z-image-turbo-lora \
  -H "Authorization: Bearer $NOVITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a portrait in anime style, soft lighting, detailed face",
    "size": "768*1024",
    "loras": [
      {
        "path": "<lora-model-path>",
        "scale": 0.8
      }
    ],
    "seed": 42
  }'

将 <lora-model-path> 替换为来自 Novita AI 模型中心 的已确认路径。path 格式和兼容的 LoRA 模型列在 Z Image Turbo LoRA API 参考 中——不要猜测模型路径；仅使用已验证的中心条目，以避免因路径无法解析而导致 TASK_STATUS_FAILED 结果。

LoRA 结果的轮询方式与基础端点完全相同。

相同 LoRA 工作流程的 Python 版本：

import os
import time
import requests

API_KEY = os.environ["NOVITA_API_KEY"]
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

def generate_with_lora(
    prompt: str,
    lora_path: str,
    lora_scale: float = 0.8,
    size: str = "1024*1024",
    seed: int = None,
) -> str:
    payload = {
        "prompt": prompt,
        "size": size,
        "loras": [{"path": lora_path, "scale": lora_scale}],
    }
    if seed is not None:
        payload["seed"] = seed

    resp = requests.post(
        "https://api.novita.ai/v3/async/z-image-turbo-lora",
        json=payload,
        headers=HEADERS,
    )
    resp.raise_for_status()
    task_id = resp.json()["task_id"]

    while True:
        result = requests.get(
            f"https://api.novita.ai/v3/async/task-result?task_id={task_id}",
            headers=HEADERS,
        )
        result.raise_for_status()
        data = result.json()
        status = data["task"]["status"]

        if status == "TASK_STATUS_SUCCEED":
            return data["images"][0]["image_url"]
        if status == "TASK_STATUS_FAILED":
            raise RuntimeError(f"Generation failed: {data['task'].get('reason', 'unknown')}")

        time.sleep(1)

LoRA 缩放指导

scale 控制 LoRA 风格的应用强度。0.8 是一个合理的默认值。如果提示词细节被 LoRA 风格覆盖，则降低该值（0.4–0.6）；如果风格不够明显，则提高该值（0.9–1.0）。堆叠多个高 scale 值的 LoRA 可能会降低图像连贯性——请先单独测试每个 LoRA。

某些 LoRA 模型需要在提示词中包含触发词才能激活其风格。在测试前，请查看 Novita AI 中心上的模型列表，了解是否有任何必需的关键词。

关键参数

基础端点（/v3/async/z-image-turbo）

参数	类型	必需	描述
prompt	string	是	目标图像的文本描述
size	string	是	输出尺寸，格式为 "width*height"，例如 "1024*1024"
seed	integer	否	可复现性种子；相同的种子和提示词返回一致的输出
enable_base64_output	boolean	否	当为 true 时，以 base64 字符串形式返回图像，而非托管 URL

LoRA 端点（/v3/async/z-image-turbo-lora）

参数	类型	必需	描述
prompt	string	是	文本提示词；如果需要，请包含 LoRA 触发词
size	string	是	输出尺寸，格式为 "width*height"
loras	array	是	一个或多个 LoRA 对象
loras[].path	string	是	来自 Novita AI 模型中心的 LoRA 模型路径
loras[].scale	number	是	影响权重；0.8 是常见的起始值
seed	integer	否	可复现性种子

在当前的文档中，enable_base64_output 未列在 LoRA 端点上。请使用轮询结果中的 URL 来获取图像。

故障排除

任务在 TASK_STATUS_PENDING 状态停留的时间超过预期。 队列深度因平台负载而异。轮询响应中的 task.eta 字段返回估计的等待时间（以秒计）。对于对延迟敏感的生产路径，请考虑跨多个任务 ID 并行提交请求和轮询。

TASK_STATUS_FAILED 立即发生或在短暂等待后发生。 读取结果中的 task.reason。常见原因包括：size 字符串格式无效、LoRA path 无法解析，或提示词触发了内容过滤。请使用最小请求进行隔离测试。

图像 URL 返回 403。 URL 生命周期由 image_url_ttl（以秒计）控制。如果您在该时间窗口之后请求 URL，访问将被拒绝。请在轮询成功后立即获取并存储图像数据。

LoRA 风格未出现在输出中。 尝试将 scale 提高到接近 1.0。验证 LoRA 是否需要触发词——如果需要，请将其添加到提示词中。

LoRA 端点返回 400 Bad Request。 确认 loras 字段是一个数组（而不是对象），并且每个条目中都存在 path 和 scale。

常见问题

Z Image Turbo 的设计目标是什么？

Z Image Turbo 针对快速文生图生成进行了优化。它适用于需要快速吞吐量的应用：预览生成、批量管线，以及 LoRA 风格化比完整 SDXL 工作流程的精细扩散控制更重要的场景。

Z Image Turbo 支持哪些尺寸？

size 参数接受一个 "width*height" 字符串。已确认支持的数值列在 Z Image Turbo 模型页面 上。正方形（1024*1024）和竖屏（768*1024）格式是安全的起点，与其他 Novita AI 图像端点一致。

我可以在一个请求中应用多个 LoRA 吗？

loras 数组接受多个条目。在实践中，堆叠高 scale 值的 LoRA 通常会降低输出质量。请先单独测试每个 LoRA，然后使用保守的 scale 值（每个条目 0.5–0.7）进行组合。

我在哪里可以找到兼容的 LoRA 路径？

浏览 Novita AI 模型中心 并查看 Z Image Turbo LoRA API 参考 以获取已确认的路径格式。不要使用来自外部来源的路径，除非您先在 Novita 平台上验证它们可以解析。

是否支持 negative_prompt？

在当前的文档中，Z Image Turbo 的两个端点都没有列出 negative_prompt 参数。如果您需要排除某些主题或风格，请在提示词中使用正面表述来引导模型远离不需要的内容，或者评估支持直接使用 negative_prompt 的标准 txt2img 端点。

我可以在单次调用中生成多张图像吗？

当前的文档中，Z Image Turbo 的两个端点都没有列出 image_num 参数。对于批量生成，请并行提交多个请求并同时轮询它们的 task_id——每个请求都是独立的。

Z Image Turbo 与标准 txt2img 端点相比如何？

标准 txt2img 端点支持广泛的配置：步数、引导比例、采样器、负面提示词、Hi-Res Fix 和精炼模型。Z Image Turbo 为了速度和更简单的请求格式而牺牲了这种可配置性。当参数控制很重要时，请使用 txt2img；当吞吐量或简洁性是优先事项时，请使用 Z Image Turbo。

推荐阅读

• Qwen Image 文生图快速入门：根据提示词生成图像
• FLUX.1 Kontext Pro vs Max vs Dev：在 Novita AI 上的对比
• 添加 LoRA 到 Stable Diffusion：全面指南