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 路徑，不涉及自架或微調。

第一步：取得您的 Novita API 金鑰

建立一個 Novita AI 帳戶，然後前往 API 金鑰管理 頁面。產生一組金鑰並將其匯出：

export NOVITA_API_KEY="your_api_key_here"

請將金鑰妥善保管，避免將其放入版本控制、客戶端套件或 Docker 映像層中。

第二步：確認端點

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。結果輪詢端點對兩者完全相同 — 一旦您的輪詢迴圈適用於其中一個，也就適用於另一個。

第三步：發送您的第一個請求

基礎端點需要 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（整數）：固定值，用於產生可重複的輸出。相同的提示和 seed 組合會回傳一致的結果。
• enable_base64_output（布林值）：當設為 true 時，結果會以 base64 編碼字串的形式回傳圖片，而非託管 URL。

第四步：輪詢結果

使用 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 並非永久有效。

第五步：查看定價、限制與常見錯誤

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 或已過期	URL 在 TTL 過期後被存取	在 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 調整建議

scale 控制 LoRA 風格的套用強度。0.8 是一個合理的預設值。如果提示的細節被 LoRA 風格覆蓋，請調低（0.4–0.6）；如果風格不夠明顯，請調高（0.9–1.0）。疊加多個 LoRA 並使用高 scale 值可能會降低連貫性 — 請先單獨測試每個 LoRA。

某些 LoRA 模型需要在提示中加入觸發詞才能啟動其風格。在測試之前，請先查看 Novita AI 中心上的模型列表，了解是否有任何必需的關鍵字。

關鍵參數

基礎端點 (/v3/async/z-image-turbo)

參數	類型	必要	說明
prompt	字串	是	目標圖片的文字描述
size	字串	是	輸出尺寸，格式為 "width*height"，例如 "1024*1024"
seed	整數	否	可重複性固定值；相同的 seed + 提示會回傳一致的輸出
enable_base64_output	布林值	否	當設為 true 時，以 base64 字串而非託管 URL 回傳圖片

LoRA 端點 (/v3/async/z-image-turbo-lora)

參數	類型	必要	說明
prompt	字串	是	文字提示；如有需要，請包含 LoRA 觸發詞
size	字串	是	輸出尺寸，格式為 "width*height"
loras	陣列	是	一個或多個 LoRA 物件
loras[].path	字串	是	來自 Novita AI 模型中心的 LoRA 模型路徑
loras[].scale	數字	是	影響權重；0.8 是常見的起點
seed	整數	否	可重複性固定值

在目前的文件說明中，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 陣列接受多個條目。在實務上，疊加多個 LoRA 並使用高 scale 值通常會降低輸出品質。請先單獨測試每個 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 on Novita AI
• Add LoRA Stable Diffusion: A Comprehensive Guide