Guide de démarrage rapide pour l'édition d'images Qwen avec des instructions textuelles

L’API Qwen Image Edit sur Novita AI modifie une image existante à l’aide d’une instruction en langage naturel, propulsée par le modèle Qwen-Image 20B. Ce guide de démarrage rapide couvre le workflow asynchrone complet : soumettez une demande d’édition avec votre image source et votre instruction, recevez un identifiant de tâche, interrogez jusqu’à la fin de l’édition, et récupérez l’URL de l’image modifiée. Le point d’accès est POST https://api.novita.ai/v3/async/qwen-image-edit.

Table des matières

Quand utiliser ce guide de démarrage rapide

Utilisez ce guide lorsque vous devez :

• Modifier une image existante via une instruction textuelle — changer les arrière-plans, échanger les styles, supprimer des éléments, faire pivoter des objets ou ajuster des vêtements sans reconstruire l’image à partir de zéro.
• Conserver les zones non touchées intactes tout en appliquant des modifications ciblées. L’architecture à double voie du modèle (Qwen2.5-VL pour la compréhension sémantique + encodeur VAE pour la préservation de l’apparence) est spécialement conçue pour empêcher les modifications de déborder dans les zones que vous n’avez pas décrites.
• Modifier précisément le texte dans les images. Qwen Image Edit gère les remplacements de texte bilingues (anglais et chinois) sur les panneaux, affiches et éléments de marque — en préservant la police, la taille et le style visuel environnant d’une manière que la plupart des générateurs d’images ne réussissent pas.

Si vous générez une nouvelle image uniquement à partir d’une instruction (aucune image d’entrée requise), utilisez plutôt le guide de démarrage rapide Qwen Image txt2img. Pour un aperçu complet des capacités du modèle, des benchmarks et de l’architecture, consultez l’article de lancement de Qwen-Image sur Novita AI.

Étape 1 : Obtenez votre clé API Novita

Créez un compte Novita AI et accédez à la gestion des clés API. Générez une clé et stockez-la comme variable d’environnement avant d’exécuter l’un des exemples de code ci-dessous :

export NOVITA_API_KEY="votre_clé_api_ici"

Gardez la clé en dehors du code côté client, des bundles frontend et du contrôle de version. Si la clé est compromise, faites-la pivoter depuis la même page de paramètres.

Étape 2 : Confirmez le point d’accès et le modèle

Élément	Valeur
Point d’accès d’édition	POST https://api.novita.ai/v3/async/qwen-image-edit
Point d’accès de sondage du résultat	GET https://api.novita.ai/v3/async/task-result?task_id=<id>
Modèle	Qwen Image Edit (20B MMDiT, architecture à double voie)
Documentation API	Référence Qwen Image Edit de Novita AI

L’API est asynchrone. L’appel d’édition renvoie immédiatement un task_id ; vous interrogez le point d’accès de résultat jusqu’à ce que le statut soit TASK_STATUS_SUCCEED. C’est le même modèle en deux étapes utilisé par tous les points d’accès de génération d’images Novita AI, y compris le point d’accès txt2img.

Le prix est de 0,02 $ par image. Vérifiez le tarif actuel sur la page de tarification Novita AI avant de construire un modèle de coût.

Étape 3 : Envoyez votre première demande d’édition

POST sur le point d’accès d’édition avec votre image source et l’instruction d’édition :

curl -s -X POST https://api.novita.ai/v3/async/qwen-image-edit \
  -H "Authorization: Bearer $NOVITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Changez l'arrière-plan en un paysage de montagne enneigée",
    "image": "https://example.com/mon-portrait.jpg"
  }'

Une réponse 200 réussie renvoie :

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

Enregistrez le task_id — vous en avez besoin pour récupérer l’image modifiée.

Étape 4 : Interrogez pour obtenir votre résultat

GET le point d’accès de résultat de tâche avec le 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"

Continuez à interroger jusqu’à ce que le champ task_status soit TASK_STATUS_SUCCEED :

{
  "task_status": "TASK_STATUS_SUCCEED",
  "images": [
    {
      "image_url": "https://...",
      "image_url_ttl": "86400",
      "image_type": "JPEG"
    }
  ]
}

L’image_url expire après la période TTL (généralement 24 heures). Téléchargez et stockez le résultat dans votre propre stockage d’objets si vous avez besoin d’un accès à long terme.

Valeurs de statut à gérer :

Statut	Signification
TASK_STATUS_QUEUED	La demande attend dans la file d’attente ; continuez à interroger
TASK_STATUS_PROCESSING	L’édition est en cours ; continuez à interroger
TASK_STATUS_SUCCEED	Terminé ; lisez l’image modifiée depuis images[0].image_url
TASK_STATUS_FAILED	La génération a échoué ; vérifiez le champ d’erreur pour la raison

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

Prix : 0,02 $ par image (vérifiez sur la page de tarification).

Limites de débit : Consultez la référence API pour les limites de débit actuelles. Si vous rencontrez une erreur 429, réduisez votre taux de requêtes et implémentez un backoff exponentiel pour les tentatives.

Erreurs HTTP courantes :

Code de statut	Cause probable
400	Corps de requête mal formé — prompt ou image manquant, format d’image invalide ou taille d’entrée non prise en charge
401	Clé API manquante ou invalide — vérifiez le format Authorization: Bearer <key>
429	Limite de débit dépassée — ajoutez un backoff et une logique de nouvelle tentative
500	Erreur côté serveur — réessayez après un court délai

Si le statut de la tâche est TASK_STATUS_FAILED, la réponse inclut généralement un message d’erreur. Les raisons courantes incluent des formats d’image non pris en charge, des images qui dépassent les limites de taille ou des instructions qui déclenchent les filtres de sécurité de contenu.

Exemple Python

Ce script soumet une demande d’édition, interroge jusqu’à la fin et affiche l’URL de l’image de sortie :

import os
import time
import requests

API_KEY = os.environ["NOVITA_API_KEY"]
BASE_URL = "https://api.novita.ai/v3/async"


def submit_edit(image: str, prompt: str, seed: int | None = None) -> str:
    payload: dict = {"prompt": prompt, "image": image}
    if seed is not None:
        payload["seed"] = seed
    response = requests.post(
        f"{BASE_URL}/qwen-image-edit",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json=payload,
    )
    response.raise_for_status()
    return response.json()["task_id"]


def poll_result(task_id: str, interval: float = 2.0, timeout: float = 120.0) -> dict:
    deadline = time.time() + timeout
    while time.time() < deadline:
        response = requests.get(
            f"{BASE_URL}/task-result",
            headers={"Authorization": f"Bearer {API_KEY}"},
            params={"task_id": task_id},
        )
        response.raise_for_status()
        data = response.json()
        status = data.get("task_status", "")
        if status == "TASK_STATUS_SUCCEED":
            return data
        if status == "TASK_STATUS_FAILED":
            raise RuntimeError(f"La tâche d'édition a échoué : {data}")
        time.sleep(interval)
    raise TimeoutError(f"La tâche {task_id} ne s'est pas terminée dans les {timeout}s")


if __name__ == "__main__":
    task_id = submit_edit(
        image="https://example.com/photo-produit.jpg",
        prompt="Changez la veste en une veste en cuir rouge, conservez l'arrière-plan",
    )
    print(f"ID de tâche : {task_id}")

    result = poll_result(task_id)
    for img in result["images"]:
        print(img["image_url"])

Exemple cURL

Workflow en deux commandes utilisant jq pour l’analyse JSON :

#!/bin/bash
# Étape 1 : soumettre la demande d'édition
TASK_ID=$(curl -s -X POST https://api.novita.ai/v3/async/qwen-image-edit \
  -H "Authorization: Bearer $NOVITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Convertissez en style aquarelle, conservez le sujet et la composition",
    "image": "https://example.com/paysage.jpg"
  }' | jq -r '.task_id')

echo "ID de tâche : $TASK_ID"

# Étape 2 : interroger jusqu'à la fin
while true; do
  RESULT=$(curl -s "https://api.novita.ai/v3/async/task-result?task_id=$TASK_ID" \
    -H "Authorization: Bearer $NOVITA_API_KEY")
  STATUS=$(echo "$RESULT" | jq -r '.task_status')
  echo "Statut : $STATUS"
  if [ "$STATUS" = "TASK_STATUS_SUCCEED" ]; then
    echo "$RESULT" | jq -r '.images[].image_url'
    break
  elif [ "$STATUS" = "TASK_STATUS_FAILED" ]; then
    echo "La tâche a échoué :"
    echo "$RESULT" | jq .
    exit 1
  fi
  sleep 2
done

Installez jq avec apt install jq (Debian/Ubuntu) ou brew install jq (macOS) s’il n’est pas déjà présent.

Paramètres clés

Paramètre	Type	Requis	Défaut	Description
prompt	chaîne	Oui	—	Instruction en langage naturel décrivant l’édition souhaitée
image	chaîne	Oui	—	Image source sous forme d’URL ou de chaîne encodée en base64
seed	entier	Non	aléatoire	Graine fixe pour des sorties reproductibles sur plusieurs exécutions
output_format	chaîne	Non	jpeg	Format de sortie — consultez la documentation API pour les valeurs acceptées

Rédiger des instructions efficaces : La spécificité compte. « Changez le texte sur le panneau publicitaire en ‘Soldes d’été’ » donne au modèle une tâche claire et délimitée. « Améliorez l’image » ne le fait pas. Lorsque vous souhaitez modifier un élément et laisser tout le reste intact, nommez ce que vous voulez préserver : « changez la couleur de la veste en rouge, conservez l’arrière-plan et le visage inchangés. » Cela aide le chemin de l’encodeur VAE à faire son travail de verrouillage des zones non touchées.

Utiliser seed pour l’itération : Lors du réglage d’une instruction, fixer la graine vous permet de comparer directement les éditions — la variation de sortie provient de votre changement d’instruction, pas d’un échantillonnage aléatoire. Une fois que vous trouvez une instruction qui fonctionne, supprimez la contrainte de la graine si vous souhaitez une diversité de sortie sur plusieurs éditions.

Cas d’utilisation typiques

Remplacement d’arrière-plan : « Remplacez l’arrière-plan par un studio blanc minimaliste » — Qwen Image Edit préserve les bords du sujet et l’éclairage tout en changeant l’environnement. Fonctionne de manière fiable lorsque le sujet a une limite claire par rapport à l’arrière-plan d’origine.

Texte dans les images : Remplacement d’enseignes de magasin, de titres d’affiches ou d’étiquettes de produits par un nouveau texte — y compris en chinois et en anglais. Le modèle préserve le style de police et le contexte visuel environnant mieux que les approches d’inpainting génératif qui ont tendance à régénérer toute la région.

Conversion de style : « Convertissez en style peinture à l’huile » ou « faites en sorte que cela ressemble à un croquis au crayon » appliqué à une image source plutôt que décrit à partir de zéro. Le chemin de l’encodeur VAE préserve la composition originale et le placement des objets tandis que l’instruction pilote la transformation de style.

Modifications au niveau des objets : Échanger des vêtements, changer les couleurs d’articles spécifiques, ajouter ou supprimer des accessoires. L’instruction doit nommer l’élément spécifique à modifier pour empêcher l’édition d’affecter les zones adjacentes.

Conversion IP et rotation d’objets : Le modèle prend en charge les changements de synthèse de vue (par exemple, faire pivoter un objet pour montrer un angle différent) et la conversion entre styles visuels pour l’imagerie de personnages ou de produits — cas d’utilisation documentés dans la présentation de Qwen-Image-Edit sur Novita AI.

Dépannage

La sortie semble inchangée : L’instruction est probablement trop vague. Rendez-la plus explicite sur l’élément à cibler : « Changez la couleur de la voiture de bleu à rouge » plutôt que « rendez-la rouge. »

Les modifications non souhaitées se propagent dans des zones non intentionnées : Pour des modifications locales très spécifiques, incluez un langage de préservation explicite dans votre instruction : « changez uniquement X, laissez Y intact. » Des instructions trop ouvertes donnent au modèle la latitude de réinterpréter toute la composition.

La tâche se termine mais l’URL de l’image renvoie 403 ou 404 : Le champ image_url_ttl (en secondes) vous indique combien de temps l’URL est valide. Si vous interrogez l’URL après le TTL, l’URL a expiré. Téléchargez l’image immédiatement après un sondage réussi.

401 Non autorisé : Vérifiez que le format de l’en-tête Authorization est exactement Bearer <key> avec un espace après Bearer. Confirmez que la clé est active et non révoquée dans la console Novita AI.

Les tâches expirent systématiquement : L’édition d’images prend plus de temps que la génération de texte — généralement 15 à 60 secondes sous charge normale. Si les tâches dépassent régulièrement votre délai d’attente, augmentez la fenêtre de sondage avant de la traiter comme un échec.

FAQ

L’image source reste-t-elle sur les serveurs de Novita ?

Votre image est téléchargée vers l’API de Novita AI via HTTPS et traitée sur leur infrastructure. Examinez les politiques de traitement des données de Novita AI avant d’envoyer des images contenant des informations personnelles sensibles, des données de santé privées ou du contenu confidentiel.

Puis-je utiliser des images encodées en base64 au lieu d’une URL ?

Oui. Passez la chaîne base64 brute dans le champ image. Consultez la référence API pour toute limite de taille sur les charges utiles base64.

Existe-t-il un paramètre de graine pour la cohérence ?

Oui — le paramètre optionnel seed fixe l’état aléatoire de sorte que la même instruction et la même image produisent des résultats cohérents. Utile pour itérer sur le libellé de l’instruction sans bruit de sortie dû au rééchantillonnage.

Puis-je utiliser ce point d’accès pour des travaux par lots ?

Oui. Soumettez plusieurs demandes d’édition en parallèle et collectez les valeurs task_id, puis interrogez-les simultanément. Chaque demande est indépendante.

Quelle est la différence entre ce point d’accès et celui de Qwen Image txt2img ?

Le point d’accès d’édition nécessite une image source et produit une version modifiée de celle-ci. Le point d’accès txt2img génère une image entièrement à partir d’une instruction textuelle — aucune image d’entrée. Utilisez le point d’accès d’édition lorsque vous avez du contenu existant à modifier ; utilisez txt2img lorsque vous créez à partir de zéro.

Articles recommandés

• Guide de démarrage rapide Qwen Image Text-to-Image pour générer des images à partir d’instructions
• Qwen-Image-Edit sur Novita AI : Édition de qualité professionnelle pour seulement 0,02 $
• Novita AI propose désormais Qwen-Image : Modèle avancé de texte vers image 20B