Inicio Rápido de Z Image Turbo para Generación Rápida de Texto a Imagen con LoRA

Z Image Turbo está disponible en Novita AI a través de dos endpoints asíncronos: POST https://api.novita.ai/v3/async/z-image-turbo para generación estándar de texto a imagen, y POST https://api.novita.ai/v3/async/z-image-turbo-lora para generación con modelos de estilo LoRA. Ambos siguen el patrón asíncrono estándar de Novita AI: envía una solicitud, recibe un task_id, luego sondea GET /v3/async/task-result hasta que la imagen esté lista. Esta guía cubre ambos endpoints de principio a fin: primera solicitud, bucle de sondeo, uso de LoRA y la referencia de parámetros que necesitas antes de escribir código en producción.

Cuándo Usar Esta Guía de Inicio Rápido

Usa esta guía cuando necesites una solicitud de trabajo verificada para Z Image Turbo antes de agregar manejo de errores, procesamiento por lotes o lógica de producción a su alrededor.

Z Image Turbo está diseñado para alto rendimiento. Se adapta a flujos de trabajo donde:

• La velocidad importa más que la máxima calidad: prototipos de pipelines, generación de vistas previas por lotes o aplicaciones en tiempo real donde la latencia es una restricción estricta.
• Deseas transferencia de estilo basada en LoRA sin configurar el conjunto completo de parámetros de txt2img. El endpoint dedicado de LoRA acepta un array loras y maneja el resto.
• Necesitas una interfaz simple de prompt-in / imagen-out con un cuerpo de solicitud mínimo.

Z Image Turbo no es la opción correcta cuando necesitas la superficie de configuración completa de Stable Diffusion: steps, guidance_scale, sampler_name, negative_prompt, hires_fix, modelos refinadores, etc. Para ese nivel de control, usa el endpoint estándar POST /v3/async/txt2img.

Esta guía cubre solo la ruta de API alojada por Novita AI. No aborda el autoalojamiento ni el ajuste fino.

Paso 1: Obtén tu Clave de API de Novita

Crea una cuenta en Novita AI y navega a gestión de claves de API. Genera una clave y expórtala:

export NOVITA_API_KEY="tu_clave_api_aqui"

Mantén la clave fuera del control de versiones, los bundles del lado del cliente y las capas de imagen Docker.

Paso 2: Confirma los Endpoints

Z Image Turbo en Novita AI utiliza dos endpoints de envío separados y un endpoint de resultados compartido:

	Base T2I	LoRA T2I
Envío	POST https://api.novita.ai/v3/async/z-image-turbo	POST https://api.novita.ai/v3/async/z-image-turbo-lora
Sondeo de resultados	GET https://api.novita.ai/v3/async/task-result?task_id=<id>	GET https://api.novita.ai/v3/async/task-result?task_id=<id>
Referencia de API	Documentación de Z Image Turbo	Documentación de Z Image Turbo LoRA

Ambos endpoints de envío devuelven solo un task_id. El endpoint de sondeo de resultados es idéntico para ambos: una vez que tu bucle de sondeo funciona para uno, funciona para el otro.

Paso 3: Envía tu Primera Solicitud

El endpoint base requiere prompt y size. Empieza aquí antes de agregar parámetros opcionales:

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": "Un horizonte de ciudad futurista al atardecer, luces de neón, fotorrealista, ultra detallado",
    "size": "1024*1024"
  }'

Una respuesta 200 exitosa devuelve:

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

Guarda el task_id. No se devuelve nada más al enviar: la generación se ejecuta de forma asíncrona.

Hay dos parámetros opcionales disponibles en el endpoint base:

• seed (entero): fija para resultados reproducibles. La misma combinación de prompt y semilla produce resultados consistentes.
• enable_base64_output (booleano): cuando es true, el resultado incluye la imagen como una cadena codificada en base64 en lugar de una URL alojada.

Paso 4: Sondear para Obtener el Resultado

Obtén el endpoint de resultado de la tarea con task_id como parámetro de consulta:

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

Una tarea completada devuelve:

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

Sondea cada 1-2 segundos hasta que task.status sea TASK_STATUS_SUCCEED o TASK_STATUS_FAILED. El campo task.eta da una estimación de segundos restantes cuando la tarea aún está en cola.

image_url_ttl es el tiempo de vida de la URL en segundos. Descarga y almacena la imagen antes de que expire el TTL: la URL alojada no es permanente.

Paso 5: Verifica Precios, Límites y Errores Comunes

El precio actual de Z Image Turbo se enumera en la página de precios de Novita AI y en la página del modelo Z Image Turbo. Verifica las tarifas antes de hacer estimaciones de costos, ya que los precios pueden cambiar.

Errores comunes:

Error	Causa	Solución
401 No autorizado	Clave de API faltante o mal formada	Confirma que el encabezado sea Authorization: Bearer <key>
400 Solicitud incorrecta	Cuerpo de solicitud inválido	Confirma que prompt y size sean cadenas; seed debe ser un entero si se proporciona
TASK_STATUS_FAILED	Generación rechazada o con error	Lee task.reason en la respuesta del resultado para el mensaje de fallo específico
La URL de la imagen devuelve 403 o está expirada	URL accedida después de que expiró el TTL	Descarga y almacena la imagen antes de que pasen los segundos de image_url_ttl

Ejemplo en Python

Flujo de trabajo completo: enviar, sondear, devolver la URL de la imagen:

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"Generación fallida: {data['task'].get('reason', 'desconocido')}")

        time.sleep(1)

if __name__ == "__main__":
    url = generate_image(
        "Un horizonte de ciudad futurista al atardecer, luces de neón, fotorrealista",
        size="1024*1024",
        seed=42,
    )
    print(url)

Generación con LoRA

El endpoint de LoRA agrega un array loras a la solicitud. Cada entrada toma un path (el identificador del modelo LoRA del hub de modelos de Novita AI) y un scale (peso de influencia):

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": "un retrato en estilo anime, iluminación suave, rostro detallado",
    "size": "768*1024",
    "loras": [
      {
        "path": "<ruta-modelo-lora>",
        "scale": 0.8
      }
    ],
    "seed": 42
  }'

Reemplaza <ruta-modelo-lora> con una ruta confirmada del hub de modelos de Novita AI. El formato de path y los modelos LoRA compatibles se enumeran en la referencia de API de Z Image Turbo LoRA: no adivines las rutas de los modelos; usa solo entradas verificadas del hub para evitar resultados TASK_STATUS_FAILED por rutas no resolubles.

El sondeo del resultado de LoRA funciona de manera idéntica al endpoint base.

Versión en Python del mismo flujo de trabajo con LoRA:

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"Generación fallida: {data['task'].get('reason', 'desconocido')}")

        time.sleep(1)

Orientación sobre la escala de LoRA

scale controla la fuerza con la que se aplica el estilo LoRA. Un valor de 0.8 es un valor predeterminado razonable. Ve más bajo (0.4–0.6) si el detalle del prompt está siendo anulado por el estilo LoRA; ve más alto (0.9–1.0) si el estilo no aparece con suficiente fuerza. Apilar múltiples LoRAs con valores de escala altos puede degradar la coherencia: prueba cada LoRA individualmente primero.

Algunos modelos LoRA requieren palabras de activación en el prompt para activar su estilo. Consulta la lista del modelo en el hub de Novita AI para ver las palabras clave requeridas antes de probar.

Parámetros Clave

Endpoint base (/v3/async/z-image-turbo)

Parámetro	Tipo	Requerido	Descripción
prompt	string	Sí	Descripción textual de la imagen objetivo
size	string	Sí	Dimensiones de salida como "ancho*alto", ej. "1024*1024"
seed	entero	No	Fija para reproducibilidad; misma semilla + prompt produce salidas consistentes
enable_base64_output	booleano	No	Cuando es true, devuelve la imagen como cadena base64 en lugar de una URL alojada

Endpoint LoRA (/v3/async/z-image-turbo-lora)

Parámetro	Tipo	Requerido	Descripción
prompt	string	Sí	Prompt textual; incluye palabras de activación de LoRA si es necesario
size	string	Sí	Dimensiones de salida como "ancho*alto"
loras	array	Sí	Uno o más objetos LoRA
loras[].path	string	Sí	Ruta del modelo LoRA desde el hub de modelos de Novita AI
loras[].scale	número	Sí	Peso de influencia; 0.8 es un punto de partida común
seed	entero	No	Fija para reproducibilidad

enable_base64_output no aparece en el endpoint LoRA en la documentación actual. Usa la URL de resultado del sondeo para recuperar la imagen.

Solución de Problemas

La tarea permanece en TASK_STATUS_PENDING más tiempo del esperado. La profundidad de la cola varía con la carga de la plataforma. El campo task.eta en la respuesta de sondeo devuelve un tiempo de espera estimado en segundos. Para rutas de producción sensibles a la latencia, considera enviar solicitudes y sondear en paralelo a través de múltiples ID de tarea.

TASK_STATUS_FAILED inmediatamente o después de una breve espera. Lee task.reason en el resultado. Causas comunes: formato de cadena size inválido, una ruta path de LoRA no resoluble, o un prompt que activó el filtrado de contenido. Aísla con una solicitud mínima.

La URL de la imagen devuelve 403. El tiempo de vida de la URL está controlado por image_url_ttl (en segundos). Si solicitas la URL después de esa ventana, se deniega el acceso. Obtén y almacena los datos de la imagen inmediatamente después de que el sondeo tenga éxito.

El estilo LoRA no aparece en la salida. Intenta aumentar scale hacia 1.0. Verifica que el LoRA no requiera palabras de activación; si las requiere, agrégalas al prompt.

400 Bad Request en el endpoint LoRA. Confirma que el campo loras sea un array (no un objeto), y que tanto path como scale estén presentes en cada entrada.

Preguntas Frecuentes

¿Para qué está diseñado Z Image Turbo?

Z Image Turbo está optimizado para la generación rápida de texto a imagen. Se adapta a aplicaciones que necesitan alto rendimiento: generación de vistas previas, pipelines por lotes y casos de uso donde la estilización basada en LoRA importa más que el control de difusión detallado de un flujo de trabajo SDXL completo.

¿Qué tamaños soporta Z Image Turbo?

El parámetro size toma una cadena "ancho*alto". Los valores admitidos confirmados se enumeran en la página del modelo Z Image Turbo. Los formatos cuadrado (1024*1024) y retrato (768*1024) son un punto de partida seguro, consistentes con otros endpoints de imagen de Novita AI.

¿Puedo aplicar múltiples LoRAs en una sola solicitud?

El array loras acepta múltiples entradas. En la práctica, apilar LoRAs con valores scale altos a menudo degrada la calidad de salida. Prueba cada LoRA individualmente primero, luego combínalos con valores de escala conservadores (0.5–0.7 por entrada).

¿Dónde encuentro rutas LoRA compatibles?

Explora el hub de modelos de Novita AI y consulta la referencia de API de Z Image Turbo LoRA para el formato de ruta confirmado. No uses rutas de fuentes externas sin verificar primero que se resuelvan en la plataforma Novita.

¿Se soporta negative_prompt?

Ninguno de los endpoints de Z Image Turbo enumera un parámetro negative_prompt en la documentación actual. Si necesitas excluir sujetos o estilos, usa una redacción positiva en el prompt para alejarte del contenido no deseado, o evalúa el endpoint estándar txt2img que soporta negative_prompt directamente.

¿Puedo generar múltiples imágenes en una sola llamada?

La documentación actual no enumera un parámetro image_num en ninguno de los endpoints de Z Image Turbo. Para generación por lotes, envía múltiples solicitudes en paralelo y sondea sus task_id de forma concurrente: cada solicitud es independiente.

¿Cómo se compara Z Image Turbo con el endpoint estándar txt2img?

El endpoint estándar txt2img soporta una amplia superficie de configuración: steps, guidance scale, sampler, negative prompt, Hi-Res Fix y modelos refinadores. Z Image Turbo intercambia esa configurabilidad por velocidad y una forma de solicitud más simple. Usa txt2img cuando el control de parámetros sea importante; usa Z Image Turbo cuando el rendimiento o la simplicidad sean la prioridad.

Artículos Recomendados

• Inicio Rápido de Qwen Image Text-to-Image para Generar Imágenes a partir de Prompts
• FLUX.1 Kontext Pro vs Max vs Dev en Novita AI
• Agregar LoRA a Stable Diffusion: Una Guía Completa