Comment utiliser l'API Qwen Image 2.1 Turbo : curl, Python et une requête testée en conditions réelles

Qwen Image 2.1 Turbo（qwen-image-2.1-turbo）est la version rapide et économique de la série d'images 2.1 d'Alibaba sur hiapi. Il accepte un prompt textuel, éventuellement 0 à 10 images de référence, et renvoie un PNG de 2048×2048. Ce guide présente une requête directement exécutable, le schéma d'entrée réellement appliqué par l'API, un appel d'édition, ainsi que ce que nous avons observé en testant l'affirmation « PNG transparent ».

Vous devez obtenir une clé API hiapi depuis la console. Les appels passent par l'API asynchrone unifiée de tâches, il n'existe donc pas de réponse d'image synchrone.

Requête minimale : génération d'image à partir de texte

curl -s -X POST https://www.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.1-turbo",
    "input": {
      "prompt": "illustration style autocollant : un shiba portant un chapeau de paille assis sur une planche de surf, aplats de couleurs, contours épais, orange corail et bleu océan",
      "aspect_ratio": "1:1",
      "seed": 42
    }
  }'
# {"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}

Interrogez ensuite GET /v1/tasks/<taskId> en boucle jusqu'à ce que data.status vaille success, puis lisez data.output[0].url.

import os, time, requests

BASE = "https://www.hiapi.ai"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

def run(input_: dict) -> str:
    r = requests.post(f"{BASE}/v1/tasks", headers=HEADERS, timeout=30,
                      json={"model": "qwen-image-2.1-turbo", "input": input_})
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]          # 注意：字段是 taskId，不是 id

    while True:
        try:
            d = requests.get(f"{BASE}/v1/tasks/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        except requests.RequestException:
            time.sleep(3)                          # 临时网络错误：继续轮询同一个 id
            continue
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] in ("fail", "failed"):
            raise RuntimeError(d)
        time.sleep(3)                              # pending / running / archiving

url = run({"prompt": "a straw-hat shiba on a surfboard, flat sticker style", "aspect_ratio": "1:1"})
open("out.png", "wb").write(requests.get(url, timeout=60).content)

Téléchargez le fichier immédiatement. L'URL de sortie se trouve sur temp.hiapi.ai, avec un horodatage expireAt (environ sept jours après la création lors de notre exécution) ; si vous devez le conserver plus longtemps, enregistrez vous-même les octets du fichier.

Schéma d'entrée (règles réellement appliquées par l'API)

Ce qui suit provient des erreurs de validation renvoyées après que nous avons volontairement envoyé des requêtes invalides ; cela reflète donc le comportement réel du point de terminaison en ligne, et non une paraphrase de la documentation :

Champ	Règle
prompt	chaîne obligatoire (le formulaire de la page modèle limite à 4500 caractères)
aspect_ratio	l'une des valeurs 1:1, 16:9, 9:16, 4:3, 3:4
image_urls	tableau d'URL d'images de référence, 0 à 10 éléments ; passer directement une chaîne est refusé avec image_urls must be an array
prompt_extend	booléen, active ou désactive l'optimisation du prompt
seed	entier, de 0 à 2147483647

Deux points diffèrent des autres modèles Qwen de la même série. Ici, il n'y a pas de champ resolution : envoyer ce champ renvoie additional properties 'resolution' not allowed. Pour 1:1, la sortie est un canevas fixe de 2048×2048, ce que nous avons vérifié en pratique. De plus, les champs inconnus sont généralement rejetés plutôt qu'ignorés. Un aspect_ratio invalide renvoie HTTP 400 avec error_code: INVALID_REQUEST, et les valeurs autorisées sont listées dans message.

Édition avec des images de référence

L'édition et la restylisation utilisent le même identifiant de modèle. Placez l'image source dans image_urls et décrivez la modification dans le prompt :

curl -s -X POST https://www.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.1-turbo",
    "input": {
      "prompt": "recolorer le chapeau de paille en violet foncé, laisser le reste inchangé",
      "image_urls": ["https://temp.hiapi.ai/.../source.png"],
      "aspect_ratio": "1:1",
      "seed": 42
    }
  }'

Résultats observés lors de notre exécution réelle

Nous avons exécuté le 2026-10-24 un appel de génération d'image à partir de texte et un appel d'édition, tous deux avec seed: 42 et aspect_ratio: "1:1".

• Latence : la génération d'image à partir de texte a atteint success environ 29 secondes après la création (horodatages created à completed de la tâche) ; l'édition a pris environ 22 secondes. Le statut passe par archiving pendant plusieurs cycles d'interrogation avant d'atteindre success, donc ne considérez pas un état non terminal comme une erreur. Ce ne sont que deux échantillons, pas un benchmark.
• Sortie : les deux ont renvoyé un PNG de 2048×2048, le résultat de la génération d'image à partir de texte faisant environ 3,9 Mo.
• Comportement de l'édition : nous avons réinjecté la première sortie et demandé de rendre le chapeau violet. Le résultat a conservé le chien, la pose, les vagues et la mise en page, et a teinté le bandeau et le ruban du chapeau de violet ; le corps tressé du chapeau est resté essentiellement couleur paille. Pour les modifications de couleur sur des objets texturés, le respect des instructions par l'édition peut n'être que partiel ; le prompt doit être précis (par exemple « recolorer le bandeau du chapeau ») plutôt que général.
• Fond transparent : le canal alpha est entièrement opaque. La page du modèle annonce une sortie PNG à fond transparent ; nous avons écrit dans le prompt « fond entièrement transparent, ne conserver que le sujet et les éclaboussures ». Le fichier renvoyé est en RGBA, mais l'alpha de chaque pixel vaut 255 (zéro pixel transparent), et les quatre coins sont blanc gris clair (par exemple (241, 243, 248, 255)). En examinant l'image, on constate que le modèle a peint un léger fond façon damier dans les pixels au lieu de les laisser transparents. La sortie de l'édition s'est comportée de la même manière (alpha minimal de 241). Ainsi, dans notre exécution, le prompt seul n'a pas produit de détourage directement utilisable sur une page colorée. Ce résultat ne correspond qu'à une seule formulation de prompt ; nous n'avons trouvé aucun champ de requête permettant d'activer la transparence (transparent est rejeté comme propriété inconnue). Si vous avez besoin d'un véritable canal alpha, prévoyez une étape de suppression d'arrière-plan, par exemple en vous référant au guide de suppression d'arrière-plan 851-labs, et vérifiez avant la mise en production par un contrôle de pixels comme Image.open(f).getchannel("A").getextrema().

Points d'attention pour la production

• Remplacez l'interrogation répétée par un callback en cas de forte concurrence : ajoutez "callback": {"url": "https://your.app/hook", "when": "final"} dans le corps de la requête de tâche, traitez le callback comme une indication, puis confirmez le résultat avec GET /v1/tasks/<taskId>.
• Conservez le taskId : si l'interrogation échoue à cause d'une erreur réseau, réinterrogez le même identifiant plutôt que de resoumettre. Une nouvelle soumission crée et facture une seconde tâche.
• Fixez seed pour obtenir des sorties comparables lorsque vous ajustez le prompt ; considérez cela comme un meilleur effort, pas comme une garantie absolue.
• Validez avant la facturation : les erreurs de schéma (HTTP 400, INVALID_REQUEST) sont renvoyées à la création, alors qu'aucune image n'a encore été générée.

Quelle version choisir

La même série propose également Qwen Image 2.1 Pro, dont le prix par image indiqué sur la page de tarification est supérieur à celui de Turbo. Les deux sont décrits comme prenant en charge la génération d'image à partir de texte, l'édition et 0 à 10 images de référence ; nous n'avons exécuté que Turbo, nous ne formulons donc aucune affirmation sur la qualité d'image relative. L'avantage de Turbo réside dans son prix plus bas et sa vitesse en 8 étapes ; si la qualité de sortie compte davantage pour vos contenus, exécutez les deux avec le même prompt et le même seed et comparez. Pour la génération Qwen 3.0 plus récente, consultez le guide de l'API Qwen Image 3.0 et le guide de Qwen Image 3.0 Pro.

Contenus associés

• Page du modèle Qwen Image 2.1 Turbo
• Tarification
• Guide de l'API Qwen Image 3.0
• Documentation

Questions fréquentes

Quel est l'identifiant du modèle ? qwen-image-2.1-turbo, envoyé via POST /v1/tasks.

Peut-on choisir la résolution de sortie ? Pas dans ce schéma : il n'y a pas de champ resolution. Choisissez un aspect_ratio parmi les cinq valeurs autorisées.

L'édition est-elle prise en charge ? Oui : passez 1 à 10 images sources dans image_urls avec un prompt d'instruction. Dans nos tests, la modification de couleur sur des zones texturées n'a été que partiellement appliquée.

Renvoie-t-il un PNG transparent ? Dans nos tests, non : le fichier est en mode RGBA, mais le canal alpha est entièrement opaque et un fond y est dessiné. Vérifiez vous-même l'alpha et, si vous avez besoin d'une vraie transparence, ajoutez une étape de suppression d'arrière-plan.

Quel est le prix ? Consultez la page de tarification ; au moment de la rédaction, c'est la moins chère des deux versions 2.1.