Blog

Tutoriel

Comment appeler qwen-image-3.0-pro/image-to-image via l'API HiAPI : curl, Python et une requête qui fonctionne

Une mise en pratique de l'intégration couvrant le modèle de tâches asynchrones, les clients curl et Python, ainsi que la gestion des erreurs

Nov 10, 2026
Image de couverture : des feuilles de papier empilées en décalage, comme une impression aux repérages décalés, papier blanc cassé aux bords noir de charbon et un feuillet intercalaire rouge rouille, avec une ombre portée droite en bas à droite.
Sur cette page

Pourquoi la génération d'images (image-to-image) est une tâche asynchrone

Lorsque vous appelez un modèle de génération d'images, vous ne demandez pas un résultat de complétion de chaîne qui peut être renvoyé en flux en quelques centaines de millisecondes. Le modèle doit charger votre image source, exécuter l'ensemble du processus de génération de type diffusion en la prenant comme condition, et encoder la sortie. Cela peut prendre de quelques secondes à quelques dizaines de secondes, et la durée varie selon la résolution et les paramètres. Maintenir une connexion HTTP ouverte pendant toute cette fenêtre n'est avantageux pour personne : les proxies expirent, les équilibreurs de charge suppriment les sockets inactifs, et vos propres threads de travail restent bloqués sur une requête qui pourrait encore échouer plus tard.

C'est pourquoi ce point de terminaison adopte le modèle « soumettre d'abord, interroger ensuite ». Votre première requête soumet une tâche et renvoie immédiatement un handle de tâche. La génération d'image s'effectue derrière ce handle. Vous lancez ensuite des requêtes indépendantes et peu coûteuses pour vérifier l'état de la tâche, jusqu'à ce qu'elle signale son achèvement, moment où la réponse contient le résultat que vous avez demandé.

Cela a quelques conséquences pratiques que vous devez intégrer à votre conception dès le départ :

  • Soumettre ne signifie pas terminer. Le succès de l'appel de soumission signifie uniquement que la plateforme a accepté votre tâche, rien de plus. Dans votre code, distinguez bien ces deux états.
  • L'ID de tâche est votre unique handle. Persistez-le. Si votre processus plante entre la soumission et l'interrogation, l'ID de tâche est ce qui vous permet de reprendre sans resoumettre (et payer à nouveau) le même travail.
  • L'interrogation est peu coûteuse mais pas gratuite. La vérification d'état est légère, mais une boucle serrée génère tout de même du trafic et peut déclencher des limitations de débit. Espacez les intervalles.
  • Les échecs arrivent de manière asynchrone. Une image corrompue ou des paramètres rejetés peuvent apparaître comme une erreur au niveau de la tâche plutôt que comme une erreur HTTP lors de la soumission. Votre code d'interrogation doit lire l'état de la tâche, pas seulement le code de statut.

Gardez ce modèle en tête : l'intégration qui suit sera directe : un appel crée le travail, une boucle l'attend, et un traitement intentionnel des trois situations qui peuvent mal tourner.

Avant d'écrire du code : ce qu'il faut préparer

Avant de toucher au terminal, rassemblez les quelques éléments dont chaque appel de ce guide dépend.

Identifiants HiAPI

Vous avez besoin d'une clé API HiAPI. Traitez-la comme un secret : chargez-la depuis une variable d'environnement plutôt que de la coller dans un script que vous pourriez valider. Les exemples ci-dessous la lisent sous le nom HIAPI_API_KEY. L'URL de base de l'API et l'identifiant exact du modèle qwen-image-3.0-pro/image-to-image sont les deux constantes auxquelles vous ferez référence tout au long.

Une image source

La génération d'images nécessite une entrée. Préparez-en une et décidez comment la fournir :

  • sous forme d'URL accessible publiquement, ou
  • sous forme de ressource téléversée ou de charge encodée, selon la forme acceptée par le point de terminaison.

Avant d'écrire l'appel, consultez le schéma de requête du modèle pour confirmer les noms de champs exacts et les formats d'image source acceptables. Fournir une image source non acceptée par le point de terminaison est la cause la plus fréquente de rejet de tâche, et l'exclure à l'avance est bien plus simple que de la déboguer à partir d'un message d'erreur.

Un client capable d'interroger

Comme l'appel est asynchrone, l'outil que vous utilisez pour envoyer la requête doit également pouvoir émettre des requêtes de suivi à répétition. curl convient pour un premier test de fumée ; tout usage plus durable doit être un script. Il n'y a pas d'URL de rappel à configurer, ni de webhook à héberger : l'interrogation est le mécanisme, alors prévoyez une boucle.

Un endroit où consulter le résultat

Décidez à l'avance à quoi ressemble « terminé » pour vous : une URL que vous pouvez ouvrir dans un navigateur, ou des octets que vous écrivez sur disque. Le savoir avant de commencer permet de voir d'un coup d'œil quand l'intégration fonctionne réellement.

Avec ces quatre éléments en main, la première requête est courte.

Envoyer une requête fonctionnelle avec curl

Le moyen le plus rapide de confirmer que votre clé, votre point de terminaison et le cycle de vie des tâches fonctionnent est une session curl en deux étapes. D'abord soumettre ; ensuite interroger.

Étape 1 : soumettre la tâche

curl -sS -X POST "$HIAPI_BASE_URL/qwen-image-3.0-pro/image-to-image" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "https://example.com/source.jpg",
    "prompt": "restyle as a soft watercolor illustration"
  }'

Détail élément par élément :

  • -X POST —— la soumission est une opération de création.
  • L'en-tête Authorization porte votre clé. En exportant une variable d'environnement plutôt qu'en la saisissant en ligne, vous évitez qu'elle reste dans l'historique du shell.
  • Content-Type: application/json —— le corps de la requête est du JSON.
  • -d —— la charge JSON. Le champ image pointe vers votre image source, prompt décrit la transformation à effectuer. Les noms de paramètres et les options acceptables proviennent du schéma de requête du modèle ; vérifiez-les là-bas plutôt que de deviner.

La réponse à une soumission réussie est un objet tâche. Il contient un identifiant — appelez-le ID de tâche — ainsi qu'un champ d'état qui doit indiquer que la tâche est en file d'attente ou en cours. Notez l'ID de tâche ; tout ce qui suit en dépend.

Étape 2 : interroger la tâche

export TASK_ID="<the id from the submit response>"

curl -sS "$HIAPI_BASE_URL/tasks/$TASK_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

À chaque appel, lisez le champ d'état. Lorsqu'il indique un état en attente ou en cours, attendez quelques secondes avant de vérifier à nouveau. Lorsqu'il indique un succès, la réponse contient l'image générée — généralement une URL récupérable, ou des données encodées. Lorsqu'il indique un échec, la réponse porte une description d'erreur expliquant la cause.

Tout le cycle de vie se résume à cela : une soumission, puis des vérifications d'état jusqu'à un état terminal. Tout ce que vous construirez ensuite ne sera qu'une version plus pratique de ces deux commandes, avec attente et gestion des erreurs.

Implémenter le même appel en Python

Répéter manuellement ces deux étapes curl devient vite fastidieux, et copier-coller la boucle d'interrogation dans chaque script est précisément la façon dont les bugs subtils se propagent. Enveloppez le modèle soumission-plus-interrogation dans une fonction réutilisable.

import os
import time
import requests

BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL_PATH = "/qwen-image-3.0-pro/image-to-image"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}


def submit_task(source_image: str, prompt: str) -> str:
    resp = requests.post(
        BASE_URL + MODEL_PATH,
        headers={**HEADERS, "Content-Type": "application/json"},
        json={"image": source_image, "prompt": prompt},
        timeout=30,
    )
    resp.raise_for_status()
    return resp.json()["id"]


def wait_for_task(task_id: str, poll_interval: float = 3.0,
                  max_wait: float = 300.0) -> dict:
    deadline = time.monotonic() + max_wait
    while time.monotonic() < deadline:
        resp = requests.get(
            f"{BASE_URL}/tasks/{task_id}",
            headers=HEADERS,
            timeout=30,
        )
        resp.raise_for_status()
        task = resp.json()
        status = task["status"]
        if status == "succeeded":
            return task
        if status == "failed":
            raise RuntimeError(f"task {task_id} failed: {task.get('error')}")
        time.sleep(poll_interval)
    raise TimeoutError(f"task {task_id} did not finish within {max_wait}s")


def generate(source_image: str, prompt: str) -> dict:
    task_id = submit_task(source_image, prompt)
    return wait_for_task(task_id)

Plusieurs choix délibérés méritent d'être soulignés :

  • Séparer la soumission de l'attente. Si la soumission échoue, vous le savez avant que toute interrogation n'ait lieu. Si vous souhaitez plus tard soumettre dans un processus et collecter dans un autre, la jointure existe déjà.
  • Chaque requête a un timeout. Une requête sans timeout peut rester suspendue indéfiniment, ce qui est précisément le mode de défaillance que l'API asynchrone est censée vous aider à éviter.
  • La boucle d'interrogation a à la fois un intervalle et une échéance globale. Sans échéance, une tâche bloquée en état d'exécution bouclerait indéfiniment. Sans intervalle, vous martèleriez le point de terminaison.
  • Les chaînes d'état sont comparées explicitement. Tout état qui n'est ni un succès ni un échec passe à l'itération suivante, ce qui est le comportement par défaut correct pour les états intermédiaires.

Appelez-la comme n'importe quelle fonction : generate(source_url, "make the background a dusk cityscape"). L'objet renvoyé est la charge de la tâche en état terminal, à partir de laquelle vous extrayez la référence de l'image.

Gérer les erreurs et les tâches échouées

Les erreurs dans un flux de travail asynchrone se répartissent en trois catégories, chacune nécessitant une réponse différente.

Rejets au niveau de la requête

Ce sont les réponses d'erreur HTTP ordinaires de l'appel de soumission — identifiants erronés ou manquants, JSON mal formé, paramètres non pris en charge, image source inaccessible. Elles arrivent avant qu'aucune tâche n'existe.

La bonne réponse consiste presque toujours à s'arrêter et à présenter le message. Réessayer une charge mal formée ne fait que gaspiller du quota et du temps. Enregistrez le code de statut et le corps de la réponse mot pour mot ; le message de validation indique généralement le champ en cause. Deux cas méritent un traitement particulier : les échecs d'authentification doivent échouer rapidement et bruyamment, car ils signifient un problème de configuration ; les réponses de limitation de débit peuvent être réessayées après un délai de repli.

Échecs au niveau de la tâche

Ici, la soumission a réussi, l'ID de tâche existe, mais le travail a échoué. La réponse d'interrogation signale un état d'échec accompagné d'une erreur.

Cette catégorie couvre les problèmes propres au modèle : image source décodable mais inutilisable, prompt rejeté, génération atteignant une limite interne. Comme ces problèmes sont spécifiques aux entrées, réessayer aveuglément reproduit généralement le même échec. Décidez au cas par cas : une erreur interne temporaire peut mériter une nouvelle tentative ; une image source rejetée n'en mérite jamais. Enregistrez l'ID de tâche avec l'erreur pour pouvoir le rattacher à une demande d'assistance.

Une interrogation qui ne se termine jamais

La soumission réussit, la tâche existe, l'interrogation est en cours — mais l'état terminal n'arrive jamais. Ce n'est pas une erreur renvoyée par la plateforme ; c'est une hypothèse dans votre code qui doit expirer.

Protégez-vous avec une échéance, comme le montre l'exemple Python. Lorsque l'échéance se déclenche, arrêtez l'interrogation. Ne renvoyez pas silencieusement un résultat à moitié terminé ; levez ou renvoyez un résultat de délai d'attente explicite pour que l'appelant décide. Conservez l'ID de tâche — la tâche peut encore se terminer après votre échéance et vous voudrez peut-être la récupérer plus tard sans la resoumettre.

Règle pratique pour ces trois catégories : traitez l'état de la tâche comme la seule source de vérité. Le code de statut HTTP vous indique si la requête a été acceptée ; les champs état et erreur de la tâche vous indiquent si le travail a réussi. Lisez les deux, et les échecs deviennent diagnostiquables plutôt que mystérieux.

L'envelopper dans du code de production

La fonction ci-dessus est une intégration utilisable, pas un service abouti. Avant qu'elle ne porte du trafic réel, resserrez quatre choses.

Des délais d'attente partout

Définissez des délais de connexion et de lecture explicites pour chaque appel — soumission, interrogation, et toute récupération ultérieure de l'image de résultat. Puis définissez une échéance globale pour l'ensemble du cycle de vie de la tâche. Les délais de la couche HTTP protègent une requête individuelle ; l'échéance de tâche protège l'opération entière.

Des nouvelles tentatives avec discernement

Ne réessayez que ce qui peut l'être sans risque. Les limitations de débit lors de l'interrogation et les erreurs réseau temporaires sont éligibles. Les charges rejetées ne le sont pas. Pour les échecs au niveau de la tâche, réessayer signifie soumettre une nouvelle tâche, ce qui est une opération distincte et plus coûteuse que de réessayer une vérification d'état — traitez-la comme une décision intentionnelle, idéalement bornée.

Des journaux contenant l'ID de tâche

Enregistrez l'ID de tâche lors de la soumission puis à chaque transition d'état, avec les informations temporelles. L'intervalle entre la soumission et le premier état terminal est la métrique que vous voudrez réellement lorsque les choses semblent lentes. Lorsqu'un utilisateur signale un mauvais résultat, l'ID de tâche est la clé qui transforme une anecdote en enregistrement traçable.

Garder l'interrogation hors du chemin de la requête

Si votre fonction s'exécute dans un gestionnaire web, une boucle d'interrogation synchrone maintient la requête ouverte pendant toute la durée de la génération — précisément le problème que la conception asynchrone vise à éviter. À la place, soumettez dans le gestionnaire, renvoyez l'ID de tâche à l'appelant, et exécutez l'attente dans un processus de travail en arrière-plan, une file d'attente ou une tâche planifiée. Le client interroge ensuite votre service, et non le modèle.

Construite dans cet ordre, l'intégration passe de « ça marche sur ma machine » à quelque chose sur quoi vous pouvez compter : soumettez, persistez le handle, attendez avec des limites, et laissez l'état de la tâche — et non l'espoir — vous dire quand arrêter.

Articles similaires

Voir tous les articles →

Commencez avec des artefacts IA persistants

Obtenez votre clé API et appelez des modèles d'image, de vidéo et d'audio via une API unique basée sur les tasks.

Lire la documentation de l'API