Início Rápido do Z Image Turbo para Geração Rápida de Texto para Imagem com LoRA

O Z Image Turbo está disponível na Novita AI por meio de dois endpoints assíncronos: POST https://api.novita.ai/v3/async/z-image-turbo para geração padrão de texto para imagem, e POST https://api.novita.ai/v3/async/z-image-turbo-lora para geração com modelos de estilo LoRA. Ambos seguem o padrão assíncrono da Novita AI — envie uma solicitação, receba um task_id, então consulte GET /v3/async/task-result até que a imagem esteja pronta. Este guia cobre ambos os endpoints de ponta a ponta: primeira solicitação, loop de polling, uso de LoRA e a referência de parâmetros que você precisa antes de escrever código de produção.

Quando Usar Este Início Rápido

Use este guia quando você precisar de uma solicitação funcional verificada para o Z Image Turbo antes de adicionar tratamento de erros, processamento em lote ou lógica de produção.

O Z Image Turbo foi projetado para alta taxa de transferência. Ele se encaixa em fluxos de trabalho onde:

• A velocidade importa mais do que a qualidade máxima — pipelines de protótipo, geração de visualizações em lote ou aplicações em tempo real onde a latência é uma restrição rígida.
• Você deseja transferência de estilo baseada em LoRA sem configurar o conjunto completo de parâmetros txt2img. O endpoint LoRA dedicado aceita um array loras e cuida do resto.
• Você precisa de uma interface simples de prompt de entrada / imagem de saída com um corpo de solicitação mínimo.

O Z Image Turbo não é a escolha certa quando você precisa da superfície de configuração completa do Stable Diffusion — steps, guidance_scale, sampler_name, negative_prompt, hires_fix, modelos de refinamento, etc. Para esse nível de controle, use o endpoint padrão POST /v3/async/txt2img.

Este guia cobre apenas o caminho da API hospedada pela Novita AI. Não aborda auto-hospedagem ou ajuste fino.

Passo 1: Obtenha sua Chave de API Novita

Crie uma conta na Novita AI e navegue até Gerenciamento de chave de API. Gere uma chave e exporte-a:

export NOVITA_API_KEY="your_api_key_here"

Mantenha a chave fora do controle de versão, bundles do lado do cliente e camadas de imagem Docker.

Passo 2: Confirme os Endpoints

O Z Image Turbo na Novita AI usa dois endpoints de envio separados e um endpoint de resultado compartilhado:

	Base T2I	LoRA T2I
Envio	POST https://api.novita.ai/v3/async/z-image-turbo	POST https://api.novita.ai/v3/async/z-image-turbo-lora
Polling de resultado	GET https://api.novita.ai/v3/async/task-result?task_id=<id>	GET https://api.novita.ai/v3/async/task-result?task_id=<id>
Referência da API	Documentação Z Image Turbo	Documentação Z Image Turbo LoRA

Ambos os endpoints de envio retornam apenas um task_id. O endpoint de polling de resultado é idêntico para ambos — uma vez que seu loop de polling funcione para um, funciona para o outro.

Passo 3: Envie Sua Primeira Solicitação

O endpoint base requer prompt e size. Comece aqui antes de adicionar parâmetros opcionais:

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"
  }'

Uma resposta 200 bem-sucedida retorna:

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

Salve o task_id. Nada mais é retornado no envio — a geração ocorre de forma assíncrona.

Dois parâmetros opcionais estão disponíveis no endpoint base:

• seed (inteiro): fixador para saídas reproduzíveis. A mesma combinação de prompt e seed retorna resultados consistentes.
• enable_base64_output (booleano): quando true, o resultado inclui a imagem como uma string codificada em base64 em vez de uma URL hospedada.

Passo 4: Consulte o Resultado

Faça GET do endpoint de resultado da tarefa com 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"

Uma tarefa concluída retorna:

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

Consulte a cada 1 a 2 segundos até que task.status seja TASK_STATUS_SUCCEED ou TASK_STATUS_FAILED. O campo task.eta fornece uma estimativa de segundos restantes quando a tarefa ainda está na fila.

image_url_ttl é o tempo de vida da URL em segundos. Baixe e armazene a imagem antes que o TTL expire — a URL hospedada não é permanente.

Passo 5: Verifique Preços, Limites e Erros Comuns

Os preços atuais do Z Image Turbo estão listados na página de preços da Novita AI e na página do modelo Z Image Turbo. Verifique as taxas antes de criar estimativas de custo, pois os preços podem mudar.

Erros comuns:

Erro	Causa	Correção
401 Unauthorized	Chave de API ausente ou malformada	Confirme se o cabeçalho é Authorization: Bearer <key>
400 Bad Request	Corpo da solicitação inválido	Confirme se prompt e size são strings; seed deve ser um inteiro se fornecido
TASK_STATUS_FAILED	Geração rejeitada ou com erro	Leia task.reason na resposta do resultado para a mensagem de falha específica
URL da imagem retorna 403 ou expirou	URL acessada após o TTL	Baixe e armazene a imagem antes que image_url_ttl segundos passem

Exemplo em Python

Fluxo de trabalho completo — envie, consulte, retorne a URL da imagem:

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)

Geração com LoRA

O endpoint LoRA adiciona um array loras à solicitação. Cada entrada recebe um path (o identificador do modelo LoRA do hub de modelos Novita AI) e um scale (peso de influência):

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
  }'

Substitua <lora-model-path> por um caminho confirmado do hub de modelos Novita AI. O formato do path e os modelos LoRA compatíveis estão listados na referência da API Z Image Turbo LoRA — não adivinhe caminhos de modelo; use apenas entradas verificadas do hub para evitar resultados TASK_STATUS_FAILED devido a caminhos não resolvíveis.

O polling do resultado LoRA funciona de forma idêntica ao endpoint base.

Versão Python do mesmo fluxo de trabalho 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"Generation failed: {data['task'].get('reason', 'unknown')}")

        time.sleep(1)

Orientação de escala LoRA

scale controla a intensidade com que o estilo LoRA é aplicado. Um valor de 0,8 é um padrão razoável. Use valores mais baixos (0,4–0,6) se os detalhes do prompt estão sendo sobrescritos pelo estilo LoRA; use valores mais altos (0,9–1,0) se o estilo não está aparecendo com força suficiente. Empilhar vários LoRAs com valores altos de scale pode degradar a coerência — teste cada LoRA individualmente primeiro.

Alguns modelos LoRA exigem palavras de ativação no prompt para ativar seu estilo. Verifique a listagem do modelo no hub Novita AI para quaisquer palavras-chave necessárias antes de testar.

Parâmetros Principais

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

Parâmetro	Tipo	Obrigatório	Descrição
prompt	string	Sim	Descrição textual da imagem alvo
size	string	Sim	Dimensões de saída como "largura*altura", ex. "1024*1024"
seed	inteiro	Não	Fixador de reprodutibilidade; mesmo seed + prompt retorna saídas consistentes
enable_base64_output	booleano	Não	Quando true, retorna a imagem como string base64 em vez de uma URL hospedada

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

Parâmetro	Tipo	Obrigatório	Descrição
prompt	string	Sim	Prompt textual; inclua palavras de ativação LoRA, se necessário
size	string	Sim	Dimensões de saída como "largura*altura"
loras	array	Sim	Um ou mais objetos LoRA
loras[].path	string	Sim	Caminho do modelo LoRA do hub de modelos Novita AI
loras[].scale	número	Sim	Peso de influência; 0,8 é um ponto de partida comum
seed	inteiro	Não	Fixador de reprodutibilidade

enable_base64_output não está listado no endpoint LoRA na documentação atual. Use a URL do resultado do polling para obter a imagem.

Solução de Problemas

A tarefa permanece em TASK_STATUS_PENDING por mais tempo que o esperado. A profundidade da fila varia conforme a carga da plataforma. O campo task.eta na resposta de polling retorna um tempo estimado de espera em segundos. Para caminhos de produção sensíveis à latência, considere enviar solicitações e fazer polling em paralelo em vários IDs de tarefa.

TASK_STATUS_FAILED imediatamente ou após uma curta espera. Leia task.reason no resultado. Causas comuns: formato de string size inválido, um path de LoRA não resolvível ou um prompt que acionou a filtragem de conteúdo. Isole com uma solicitação mínima.

URL da imagem retorna 403. O tempo de vida da URL é controlado por image_url_ttl (em segundos). Se você solicitar a URL após essa janela, o acesso é negado. Busque e armazene os dados da imagem imediatamente após o polling ser bem-sucedido.

O estilo LoRA não está aparecendo na saída. Tente aumentar scale para 1,0. Verifique se o LoRA exige palavras de ativação — se sim, adicione-as ao prompt.

400 Bad Request no endpoint LoRA. Confirme que o campo loras é um array (não um objeto), e que tanto path quanto scale estão presentes em cada entrada.

FAQ

Para que serve o Z Image Turbo?

O Z Image Turbo é otimizado para geração rápida de texto para imagem. Ele é adequado para aplicações que precisam de alta taxa de transferência: geração de visualizações, pipelines em lote e casos de uso onde a estilização baseada em LoRA importa mais do que o controle fino de difusão de um fluxo de trabalho SDXL completo.

Quais tamanhos o Z Image Turbo suporta?

O parâmetro size aceita uma string "largura*altura". Os valores suportados confirmados estão listados na página do modelo Z Image Turbo. Formatos quadrado (1024*1024) e retrato (768*1024) são um ponto de partida seguro, consistentes com outros endpoints de imagem Novita AI.

Posso aplicar vários LoRAs em uma única solicitação?

O array loras aceita múltiplas entradas. Na prática, empilhar LoRAs com valores altos de scale geralmente degrada a qualidade da saída. Teste cada LoRA individualmente primeiro, depois combine com valores de scale conservadores (0,5–0,7 por entrada).

Onde encontro caminhos LoRA compatíveis?

Navegue pelo hub de modelos Novita AI e verifique a referência da API Z Image Turbo LoRA para o formato de caminho confirmado. Não use caminhos de fontes externas sem antes verificar se eles resolvem na plataforma Novita.

O negative_prompt é suportado?

Nenhum dos endpoints do Z Image Turbo lista um parâmetro negative_prompt na documentação atual. Se você precisar excluir assuntos ou estilos, use frases positivas no prompt para desviar de conteúdo indesejado, ou avalie o endpoint padrão txt2img que suporta negative_prompt diretamente.

Posso gerar várias imagens em uma única chamada?

A documentação atual não lista um parâmetro image_num em nenhum dos endpoints do Z Image Turbo. Para geração em lote, envie várias solicitações em paralelo e consulte seus task_id concorrentemente — cada solicitação é independente.

Como o Z Image Turbo se compara ao endpoint padrão txt2img?

O endpoint padrão txt2img suporta uma ampla superfície de configuração: steps, guidance scale, sampler, negative prompt, Hi-Res Fix e modelos de refinamento. O Z Image Turbo troca essa configuralidade por velocidade e uma forma de solicitação mais simples. Use txt2img quando o controle de parâmetros for importante; use Z Image Turbo quando a taxa de transferência ou simplicidade for a prioridade.

Artigos Recomendados

• Início Rápido do Qwen Image Text-to-Image para Gerar Imagens a partir de Prompts
• FLUX.1 Kontext Pro vs Max vs Dev na Novita AI
• Adicionar LoRA Stable Diffusion: Um Guia Abrangente