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 и справочник параметров, необходимый перед написанием production-кода.

Когда использовать этот быстрый старт

Используйте это руководство, когда вам нужен проверенный работающий запрос для Z Image Turbo перед добавлением обработки ошибок, пакетирования или production-логики.

Z Image Turbo спроектирован для высокой пропускной способности. Он подходит для сценариев, где:

• Скорость важнее максимального качества — прототипирование пайплайнов, пакетная генерация превью или real-time приложения с жесткими ограничениями по задержке.
• Вы хотите перенос стиля на основе LoRA без настройки полного набора параметров txt2img. Выделенный LoRA-эндпоинт принимает массив loras и обрабатывает остальное.
• Вам нужен простой интерфейс «промпт на входе — изображение на выходе» с минимальным телом запроса.

Z Image Turbo не подходит, когда вам нужна полная поверхность конфигурации Stable Diffusion — steps, guidance_scale, sampler_name, negative_prompt, hires_fix, рефайнеры и т.д. Для такого уровня управления используйте стандартный эндпоинт POST /v3/async/txt2img.

Это руководство охватывает только путь API, размещенного на Novita AI. Оно не рассматривает самостоятельный хостинг или тонкую настройку.

Шаг 1: Получите ключ API Novita

Создайте аккаунт Novita AI и перейдите в управление ключами API. Сгенерируйте ключ и экспортируйте его:

export NOVITA_API_KEY="your_api_key_here"

Не храните ключ в системах контроля версий, клиентских сборках и слоях Docker-образов.

Шаг 2: Подтвердите конечные точки

Z Image Turbo на Novita AI использует две отдельные точки отправки и одну общую точку получения результата:

	Базовая 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": "Футуристический городской пейзаж в сумерках, неоновые огни, фотореалистично, ультрадетально",
    "size": "1024*1024"
  }'

Успешный ответ 200 возвращает:

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

Сохраните task_id. Больше ничего при отправке не возвращается — генерация выполняется асинхронно.

В базовом эндпоинте доступны два необязательных параметра:

• seed (целое число): фиксатор для воспроизводимых результатов. Одинаковая комбинация промпта и seed дает постоянные результаты.
• enable_base64_output (логическое): если true, результат включает изображение в виде строки в формате base64, а не размещенного URL.

Шаг 4: Опрашивайте результат

Выполните GET-запрос к точке получения результата с task_id в качестве параметра запроса:

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 или истек	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(
        "Футуристический городской пейзаж в сумерках, неоновые огни, фотореалистично",
        size="1024*1024",
        seed=42,
    )
    print(url)

Генерация с LoRA

LoRA-эндпоинт добавляет в запрос массив loras. Каждый элемент содержит path (идентификатор LoRA-модели из хаба моделей Novita AI) и 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": "портрет в аниме-стиле, мягкое освещение, детализированное лицо",
    "size": "768*1024",
    "loras": [
      {
        "path": "<путь-к-lora-модели>",
        "scale": 0.8
      }
    ],
    "seed": 42
  }'

Замените <путь-к-lora-модели> на подтвержденный путь из хаба моделей Novita AI. Формат path и совместимые LoRA-модели перечислены в справочнике API Z Image Turbo LoRA — не угадывайте пути моделей; используйте только проверенные записи из хаба, чтобы избежать 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)

Рекомендации по параметру scale

scale контролирует, насколько сильно применяется стиль LoRA. Значение 0.8 — разумное значение по умолчанию. Уменьшите (0.4–0.6), если стиль LoRA переопределяет детали промпта; увеличьте (0.9–1.0), если стиль проявляется недостаточно сильно. Использование нескольких LoRA с высокими значениями scale может снизить согласованность — сначала тестируйте каждую LoRA отдельно.

Некоторые LoRA-модели требуют слов-триггеров в промпте для активации своего стиля. Проверьте описание модели в хабе Novita AI на наличие обязательных ключевых слов перед тестированием.

Ключевые параметры

Базовый эндпоинт (/v3/async/z-image-turbo)

Параметр	Тип	Обязательный	Описание
prompt	string	Да	Текстовое описание целевого изображения
size	string	Да	Размеры вывода в формате "ширина*высота", например "1024*1024"
seed	integer	Нет	Фиксатор воспроизводимости; одинаковый seed + промпт дают постоянные результаты
enable_base64_output	boolean	Нет	Если true, возвращает изображение в виде строки base64 вместо URL

LoRA-эндпоинт (/v3/async/z-image-turbo-lora)

Параметр	Тип	Обязательный	Описание
prompt	string	Да	Текстовый промпт; при необходимости включите слова-триггеры LoRA
size	string	Да	Размеры вывода в формате "ширина*высота"
loras	array	Да	Один или несколько объектов LoRA
loras[].path	string	Да	Путь к LoRA-модели из хаба моделей Novita AI
loras[].scale	number	Да	Вес влияния; 0.8 — обычная отправная точка
seed	integer	Нет	Фиксатор воспроизводимости

enable_base64_output не указан для LoRA-эндпоинта в текущей документации. Используйте URL результата из опроса для получения изображения.

Устранение неполадок

Задача остается в статусе TASK_STATUS_PENDING дольше ожидаемого. Глубина очереди варьируется в зависимости от загрузки платформы. Поле task.eta в ответе опроса возвращает расчетное время ожидания в секундах. Для чувствительных к задержкам production-сценариев рассмотрите возможность параллельной отправки запросов и опроса нескольких task_id.

TASK_STATUS_FAILED немедленно или после короткого ожидания. Прочитайте task.reason в результате. Распространенные причины: неверный формат строки size, неразрешимый path LoRA или промпт, вызвавший фильтрацию контента. Изолируйте с помощью минимального запроса.

URL изображения возвращает 403. Время жизни URL определяется image_url_ttl (в секундах). Если вы запрашиваете URL после истечения этого окна, доступ запрещен. Загрузите и сохраните данные изображения сразу после успешного опроса.

Стиль LoRA не отображается в выводе. Попробуйте увеличить scale до 1.0. Проверьте, не требуются ли для LoRA слова-триггеры — если да, добавьте их в промпт.

400 Bad Request на LoRA-эндпоинте. Убедитесь, что поле loras является массивом (а не объектом), и что в каждой записи присутствуют и path, и scale.

Часто задаваемые вопросы

Для чего предназначен Z Image Turbo?

Z Image Turbo оптимизирован для быстрой генерации изображений по тексту. Он подходит для приложений, требующих высокой пропускной способности: генерация превью, пакетные пайплайны и сценарии, где стилизация на основе LoRA важнее тонкого управления диффузией в полном рабочем процессе SDXL.

Какие размеры поддерживает Z Image Turbo?

Параметр size принимает строку "ширина*высота". Подтвержденные поддерживаемые значения перечислены на странице модели Z Image Turbo. Квадратный (1024*1024) и портретный (768*1024) форматы — безопасная отправная точка, соответствующая другим эндпоинтам изображений Novita AI.

Можно ли применить несколько LoRA в одном запросе?

Массив loras принимает несколько записей. На практике объединение LoRA с высокими значениями scale часто снижает качество вывода. Сначала тестируйте каждую LoRA отдельно, затем комбинируйте с консервативными значениями scale (0.5–0.7 на запись).

Где найти совместимые пути LoRA?

Просмотрите хаб моделей Novita AI и проверьте справочник API Z Image Turbo LoRA для подтвержденного формата пути. Не используйте пути из внешних источников, предварительно не убедившись, что они разрешаются на платформе Novita.

Поддерживается ли negative_prompt?

Ни один из эндпоинтов Z Image Turbo не содержит параметр negative_prompt в текущей документации. Если вам нужно исключить объекты или стили, используйте положительные формулировки в промпте, чтобы отойти от нежелательного контента, или рассмотрите стандартный эндпоинт txt2img, который поддерживает negative_prompt напрямую.

Можно ли сгенерировать несколько изображений за один вызов?

Текущая документация не содержит параметр image_num ни для одного из эндпоинтов Z Image Turbo. Для пакетной генерации отправляйте несколько запросов параллельно и опрашивайте их task_id одновременно — каждый запрос независим.

Как Z Image Turbo сравнивается со стандартным эндпоинтом txt2img?

Стандартный эндпоинт txt2img поддерживает широкую поверхность конфигурации: steps, guidance scale, семплер, negative prompt, Hi-Res Fix и рефайнеры. Z Image Turbo обменивает эту конфигурируемость на скорость и простую форму запроса. Используйте txt2img, когда важен контроль параметров; используйте Z Image Turbo, когда приоритетом является пропускная способность или простота.

Рекомендуемые статьи

• Qwen Image Text-to-Image Quick Start for Generating Images from Prompts
• FLUX.1 Kontext Pro vs Max vs Dev on Novita AI
• Add LoRA Stable Diffusion: A Comprehensive Guide