Démarrage rapide de Z Image Turbo pour la génération texte-image rapide avec LoRA

Z Image Turbo est disponible sur Novita AI via deux points de terminaison asynchrones : POST https://api.novita.ai/v3/async/z-image-turbo pour la génération texte-image standard, et POST https://api.novita.ai/v3/async/z-image-turbo-lora pour la génération avec des modèles de style LoRA. Les deux suivent le modèle asynchrone standard de Novita AI — soumettez une requête, recevez un task_id, puis interrogez GET /v3/async/task-result jusqu’à ce que l’image soit prête. Ce guide couvre les deux points de terminaison de bout en bout : première requête, boucle de polling, utilisation de LoRA, et la référence des paramètres dont vous avez besoin avant d’écrire du code de production.

Quand utiliser ce guide de démarrage rapide

Utilisez ce guide lorsque vous avez besoin d’une requête de travail vérifiée pour Z Image Turbo avant d’ajouter la gestion des erreurs, le traitement par lots ou la logique de production autour de celle-ci.

Z Image Turbo est conçu pour un débit rapide. Il convient aux flux de travail où :

• La vitesse compte plus que la qualité maximale — pipelines de prototypage, génération d’aperçus par lots, ou applications en temps réel où la latence est une contrainte stricte.
• Vous souhaitez un transfert de style basé sur LoRA sans configurer l’ensemble complet des paramètres txt2img. Le point de terminaison LoRA dédié accepte un tableau loras et gère le reste.
• Vous avez besoin d’une interface simple prompt-in / image-out avec un corps de requête minimal.

Z Image Turbo n’est pas le bon choix lorsque vous avez besoin de la surface de configuration complète de Stable Diffusion — steps, guidance_scale, sampler_name, negative_prompt, hires_fix, modèles de raffinement, etc. Pour ce niveau de contrôle, utilisez le point de terminaison standard POST /v3/async/txt2img.

Ce guide couvre uniquement le chemin API hébergé par Novita AI. Il ne traite pas de l’auto-hébergement ou du fine-tuning.

Étape 1 : Obtenez votre clé API Novita

Créez un compte Novita AI et accédez à gestion des clés API. Générez une clé et exportez-la :

export NOVITA_API_KEY="votre_cle_api_ici"

Gardez la clé hors du contrôle de version, des bundles côté client et des couches d’image Docker.

Étape 2 : Confirmez les points de terminaison

Z Image Turbo sur Novita AI utilise deux points de terminaison de soumission distincts et un point de terminaison de résultat partagé :

	Base T2I	LoRA T2I
Soumission	POST https://api.novita.ai/v3/async/z-image-turbo	POST https://api.novita.ai/v3/async/z-image-turbo-lora
Interrogation du résultat	GET https://api.novita.ai/v3/async/task-result?task_id=<id>	GET https://api.novita.ai/v3/async/task-result?task_id=<id>
Référence API	Documentation Z Image Turbo	Documentation Z Image Turbo LoRA

Les deux points de terminaison de soumission ne renvoient qu’un task_id. Le point de terminaison d’interrogation du résultat est identique pour les deux — une fois que votre boucle de polling fonctionne pour l’un, elle fonctionne pour l’autre.

Étape 3 : Envoyez votre première requête

Le point de terminaison de base nécessite prompt et size. Commencez ici avant d’ajouter des paramètres optionnels :

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": "Une skyline de ville futuriste au crépuscule, lumières néon, photoréaliste, ultra-détaillée",
    "size": "1024*1024"
  }'

Une réponse 200 réussie renvoie :

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

Enregistrez le task_id. Rien d’autre n’est renvoyé lors de la soumission — la génération s’exécute de manière asynchrone.

Deux paramètres optionnels sont disponibles sur le point de terminaison de base :

• seed (entier) : épingle pour des sorties reproductibles. La même combinaison prompt et seed donne des résultats cohérents.
• enable_base64_output (booléen) : lorsque true, le résultat inclut l’image sous forme de chaîne encodée en base64 plutôt qu’une URL hébergée.

Étape 4 : Interrogez le résultat

Utilisez GET sur le point de terminaison du résultat de la tâche avec task_id comme paramètre de requête :

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

Une tâche terminée renvoie :

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

Interrogez toutes les 1 à 2 secondes jusqu’à ce que task.status soit TASK_STATUS_SUCCEED ou TASK_STATUS_FAILED. Le champ task.eta donne une estimation des secondes restantes lorsque la tâche est encore en file d’attente.

image_url_ttl est la durée de vie de l’URL en secondes. Téléchargez et stockez l’image avant l’expiration du TTL — l’URL hébergée n’est pas permanente.

Étape 5 : Vérifiez la tarification, les limites et les erreurs courantes

La tarification actuelle de Z Image Turbo est listée sur la page de tarification Novita AI et la page du modèle Z Image Turbo. Vérifiez les tarifs avant d’établir des estimations de coûts, car les prix peuvent changer.

Erreurs courantes :

Erreur	Cause	Correctif
401 Non autorisé	Clé API manquante ou mal formée	Confirmez que l’en-tête est Authorization: Bearer <clé>
400 Mauvaise requête	Corps de requête invalide	Confirmez que prompt et size sont des chaînes ; seed doit être un entier si fourni
TASK_STATUS_FAILED	Génération rejetée ou en erreur	Lisez task.reason dans la réponse du résultat pour le message d’échec spécifique
L’URL de l’image renvoie 403 ou est expirée	URL accédée après l’expiration du TTL	Téléchargez et stockez l’image avant que image_url_ttl secondes ne se soient écoulées

Exemple Python

Flux de travail complet — soumettre, interroger, retourner l’URL de l’image :

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)

Génération LoRA

Le point de terminaison LoRA ajoute un tableau loras à la requête. Chaque entrée prend un path (l’identifiant du modèle LoRA depuis le hub de modèles Novita AI) et un scale (poids d’influence) :

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 portrait en style anime, éclairage doux, visage détaillé",
    "size": "768*1024",
    "loras": [
      {
        "path": "<chemin-modele-lora>",
        "scale": 0.8
      }
    ],
    "seed": 42
  }'

Remplacez <chemin-modele-lora> par un chemin confirmé depuis le hub de modèles Novita AI. Le format du path et les modèles LoRA compatibles sont listés dans la référence API Z Image Turbo LoRA — ne devinez pas les chemins de modèles ; utilisez uniquement des entrées vérifiées du hub pour éviter les résultats TASK_STATUS_FAILED dus à des chemins non résolubles.

L’interrogation du résultat LoRA fonctionne de manière identique au point de terminaison de base.

Version Python du même flux de travail 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)

Guide pour l’échelle LoRA

scale contrôle la force d’application du style LoRA. Une valeur de 0.8 est une valeur par défaut raisonnable. Descendez plus bas (0.4–0.6) si les détails du prompt sont écrasés par le style LoRA ; montez plus haut (0.9–1.0) si le style n’apparaît pas assez fortement. L’empilement de plusieurs LoRA avec des valeurs d’échelle élevées peut dégrader la cohérence — testez chaque LoRA individuellement d’abord.

Certains modèles LoRA nécessitent des mots déclencheurs dans le prompt pour activer leur style. Vérifiez la fiche du modèle sur le hub Novita AI pour tout mot-clé requis avant de tester.

Paramètres clés

Point de terminaison de base (/v3/async/z-image-turbo)

Paramètre	Type	Requis	Description
prompt	chaîne	Oui	Description textuelle de l’image cible
size	chaîne	Oui	Dimensions de sortie au format "largeur*hauteur", ex. "1024*1024"
seed	entier	Non	Épingle de reproductibilité ; même seed + prompt retourne des sorties cohérentes
enable_base64_output	booléen	Non	Lorsque true, retourne l’image sous forme de chaîne base64 au lieu d’une URL hébergée

Point de terminaison LoRA (/v3/async/z-image-turbo-lora)

Paramètre	Type	Requis	Description
prompt	chaîne	Oui	Prompt textuel ; incluez les mots déclencheurs LoRA si nécessaire
size	chaîne	Oui	Dimensions de sortie au format "largeur*hauteur"
loras	tableau	Oui	Un ou plusieurs objets LoRA
loras[].path	chaîne	Oui	Chemin du modèle LoRA depuis le hub de modèles Novita AI
loras[].scale	nombre	Oui	Poids d’influence ; 0.8 est un point de départ courant
seed	entier	Non	Épingle de reproductibilité

enable_base64_output n’est pas listé sur le point de terminaison LoRA dans la documentation actuelle. Utilisez l’URL de résultat de l’interrogation pour la récupération d’image.

Dépannage

La tâche reste dans l’état TASK_STATUS_PENDING plus longtemps que prévu. La profondeur de la file d’attente varie avec la charge de la plateforme. Le champ task.eta dans la réponse d’interrogation retourne une estimation du temps d’attente en secondes. Pour les chemins de production sensibles à la latence, envisagez de soumettre des requêtes et d’interroger en parallèle sur plusieurs ID de tâche.

TASK_STATUS_FAILED immédiatement ou après une courte attente. Lisez task.reason dans le résultat. Causes courantes : format de chaîne size invalide, path LoRA non résoluble, ou un prompt ayant déclenché le filtrage de contenu. Isolez avec une requête minimale.

L’URL de l’image renvoie 403. La durée de vie de l’URL est contrôlée par image_url_ttl (en secondes). Si vous demandez l’URL après cette fenêtre, l’accès est refusé. Récupérez et stockez les données de l’image immédiatement après la réussite de l’interrogation.

Le style LoRA n’apparaît pas dans la sortie. Essayez d’augmenter scale vers 1.0. Vérifiez si le LoRA nécessite des mots déclencheurs — si oui, ajoutez-les au prompt.

400 Bad Request sur le point de terminaison LoRA. Confirmez que le champ loras est un tableau (pas un objet), et que path et scale sont présents dans chaque entrée.

FAQ

À quoi sert Z Image Turbo ?

Z Image Turbo est optimisé pour la génération rapide texte-image. Il convient aux applications nécessitant un débit rapide : génération d’aperçus, pipelines par lots, et cas d’utilisation où la stylisation basée sur LoRA prime sur le contrôle fin de la diffusion d’un flux SDXL complet.

Quelles tailles Z Image Turbo prend-il en charge ?

Le paramètre size prend une chaîne "largeur*hauteur". Les valeurs prises en charge confirmées sont listées sur la page du modèle Z Image Turbo. Les formats carré (1024*1024) et portrait (768*1024) sont un point de départ sûr, cohérent avec les autres points de terminaison d’image Novita AI.

Puis-je appliquer plusieurs LoRA dans une seule requête ?

Le tableau loras accepte plusieurs entrées. En pratique, l’empilement de LoRA avec des valeurs scale élevées dégrade souvent la qualité de sortie. Testez chaque LoRA individuellement d’abord, puis combinez avec des valeurs d’échelle conservatrices (0.5–0.7 par entrée).

Où trouver des chemins LoRA compatibles ?

Parcourez le hub de modèles Novita AI et consultez la référence API Z Image Turbo LoRA pour le format de chemin confirmé. N’utilisez pas de chemins provenant de sources externes sans vérifier d’abord qu’ils résolvent sur la plateforme Novita.

negative_prompt est-il pris en charge ?

Aucun des points de terminaison Z Image Turbo ne liste un paramètre negative_prompt dans la documentation actuelle. Si vous devez exclure des sujets ou des styles, utilisez une formulation positive dans le prompt pour vous éloigner du contenu indésirable, ou évaluez le point de terminaison standard txt2img qui prend en charge negative_prompt directement.

Puis-je générer plusieurs images en un seul appel ?

La documentation actuelle ne liste pas de paramètre image_num sur l’un ou l’autre des points de terminaison Z Image Turbo. Pour la génération par lots, soumettez plusieurs requêtes en parallèle et interrogez leurs task_id simultanément — chaque requête est indépendante.

Comment Z Image Turbo se compare-t-il au point de terminaison standard txt2img ?

Le point de terminaison standard txt2img prend en charge une large surface de configuration : steps, guidance scale, sampler, negative prompt, Hi-Res Fix, et modèles de raffinement. Z Image Turbo échange cette configurabilité contre la vitesse et une forme de requête plus simple. Utilisez txt2img lorsque le contrôle des paramètres est important ; utilisez Z Image Turbo lorsque le débit ou la simplicité est la priorité.

Articles recommandés

• Guide de démarrage rapide Qwen Image Text-to-Image pour générer des images à partir de prompts
• FLUX.1 Kontext Pro vs Max vs Dev sur Novita AI
• Ajouter LoRA Stable Diffusion : un guide complet