HiAPI
Blog

Tutoriel

Comment utiliser qwen-image-2.0-pro via l'API HiAPI : curl, Python et une requête fonctionnelle

Exercice d'intégration pratique pour développeurs : premier appel réussi, anatomie de la requête et dépannage

Nov 17, 2026
Image de couverture minimaliste en superposition de couches de papier : sur un fond crème, plusieurs fines feuilles couleur graphite se décalent successivement en retrait dans une faible profondeur de champ, une feuille couleur terre cuite au centre servant d'accent.
Sur cette page

Ce que qwen-image-2.0-pro apporte aux utilisateurs de l'API

qwen-image-2.0-pro est un modèle de génération d'images appelé via HTTP. Du point de vue de votre code, il se comporte comme un point de terminaison de complétion de chat : vous envoyez une charge utile JSON décrivant l'image souhaitée, puis vous recevez une réponse JSON contenant l'image générée.

L'avantage d'y accéder via l'API HiAPI réside dans la cohérence. Une clé API, une URL de base, une structure de requête commune à tous les modèles. Si vous changez ensuite l'identifiant du modèle ou ajustez les paramètres, le code environnant reste inchangé. Vous n'avez pas besoin d'apprendre un nouveau SDK ni de gérer plusieurs jeux d'identifiants pour chaque modèle d'image que vous essayez.

Ce tutoriel commence par un premier appel complet en curl, puis le porte en Python, explique comment extraire l'image de la réponse, et se termine par une liste de vérification de dépannage et une petite enveloppe réutilisable. Tous les exemples utilisent la même charge utile et la même variable d'environnement de clé, de sorte que ce qui fonctionne dans le terminal s'exécute sans modification dans un script.

Prérequis et préparation de la clé

Avant d'écrire la moindre ligne de code, assurez-vous que les trois éléments suivants sont prêts.

1. Compte HiAPI et clé API

Créez un compte et générez une clé API dans le tableau de bord. La clé est confidentielle ; traitez-la comme un mot de passe. Ne la collez pas dans un fichier source qui sera commité dans le contrôle de version.

2. Exporter la clé comme variable d'environnement

Les exemples suivants lisent la clé depuis HIAPI_API_KEY, afin que les mêmes commandes et scripts fonctionnent sans modification en local comme en CI.

export HIAPI_API_KEY="your_key_here"

Sous Windows PowerShell, utilisez $env:HIAPI_API_KEY = "your_key_here". En CI, définissez-la comme variable d'environnement secrète dans la configuration du pipeline.

3. Un outil pour émettre des requêtes HTTP

curl est généralement préinstallé. Pour Python, vous avez besoin de Python 3 et de la bibliothèque requests :

pip install requests

Avant de continuer, vous pouvez vérifier que le shell voit bien la clé :

# macOS / Linux
echo "${HIAPI_API_KEY:0:4}..."

Si rien ne s'affiche, la variable n'est pas définie et toutes les requêtes échoueront avec une erreur d'authentification. Résolvez ce point en premier.

La requête minimale fonctionnelle avec curl

Le moyen le plus rapide de vérifier la connectivité est d'exécuter un appel curl en lisant la clé depuis la variable d'environnement. La charge utile est un objet JSON contenant un champ model et un tableau messages de style complétion de chat.

curl -sS https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.0-pro",
    "messages": [
      {
        "role": "user",
        "content": "A small ceramic mug on a wooden table, soft morning light, product photo"
      }
    ]
  }'

Trois détails importants ici. L'en-tête Authorization utilise le schéma Bearer. La valeur model doit correspondre exactement à l'identifiant du modèle. content est une chaîne simple décrivant l'image.

Si la requête réussit, vous verrez la réponse JSON s'afficher dans le terminal. Si elle échoue, vous verrez le code de statut HTTP et le message d'erreur. Vérifiez le code de statut avant de lire le corps de la réponse : 401 indique une clé erronée ou absente, 400 signale généralement une charge utile mal formée, et 404 ou une erreur de modèle introuvable indique un identifiant de modèle incorrect.

Dès que cette commande renvoie une réponse réussie, la connectivité est confirmée et vous pouvez passer à l'écriture du code.

La même requête en Python

Portez l'appel en Python en conservant exactement la même charge utile. La seule différence réside dans la lecture de la variable d'environnement et la sérialisation de la requête.

import json
import os

import requests

api_key = os.environ["HIAPI_API_KEY"]

payload = {
    "model": "qwen-image-2.0-pro",
    "messages": [
        {
            "role": "user",
            "content": "A small ceramic mug on a wooden table, soft morning light, product photo",
        }
    ],
}

response = requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=120,
)

response.raise_for_status()
data = response.json()
print(json.dumps(data, indent=2))

Notez que json=payload fait en sorte que requests définisse automatiquement l'en-tête Content-Type et sérialise le corps de la requête. Le timeout est important car la génération d'images peut être plus longue qu'une complétion de texte classique ; 120 secondes est un point de départ raisonnable. raise_for_status() transforme les codes de statut d'erreur en exceptions, de sorte qu'un échec ne passe pas inaperçu.

Exécutez ce script et vous devriez obtenir le même JSON que celui vu avec curl. Sinon, votre environnement diffère du shell où curl a réussi, le plus souvent à cause de la variable de clé.

Lire la réponse et traiter la sortie image

La réponse suit la structure de complétion de chat ; l'image générée est donc récupérée par le même chemin que celui utilisé pour traiter une réponse texte. Inspectez d'abord le JSON imprimé ; sa structure vous sera familière :

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "..."
      }
    }
  ]
}

L'image générée apparaît dans le contenu du message de l'assistant, généralement sous forme d'URL ou de charge utile encodée en base64, selon la manière dont le modèle renvoie les médias. Ne présumez pas de laquelle il s'agit ; lisez la valeur et branchez selon son préfixe :

content = data["choices"][0]["message"]["content"]

if isinstance(content, str) and content.startswith("http"):
    image_url = content
    # Download and save if you want a local copy
    image_bytes = requests.get(image_url, timeout=60).content
    with open("output.png", "wb") as f:
        f.write(image_bytes)
    print("saved output.png from URL")
else:
    # Treat as base64-encoded image data
    import base64

    image_bytes = base64.b64decode(content)
    with open("output.png", "wb") as f:
        f.write(image_bytes)
    print("saved output.png from base64")

Deux remarques pratiques. Si le contenu est une URL, considérez-la comme un lien temporaire et téléchargez-la rapidement, plutôt que de la lier directement dans votre produit. S'il s'agit de base64, isolez le décodage afin qu'une charge utile mal formée lève une erreur capturable. Écrivez toujours la réponse brute dans un fichier journal avant de l'analyser, ce qui vous permet de déboguer sans réexécuter une requête potentiellement lente.

Liste de vérification pour les requêtes en échec

Quand une requête échoue, ne vous empressez pas de réécrire tout l'appel. Effectuez les vérifications suivantes dans l'ordre et arrêtez-vous au premier échec. Chaque vérification isole une variable.

1. Authentification

Vérifiez d'abord le code de statut. 401 signifie que la clé est absente, expirée ou mal formée. Confirmez que la variable d'environnement est définie dans le shell courant, que vous utilisez bien le préfixe Bearer, et que l'en-tête ne contient pas d'espace final.

2. Identifiant de modèle

Une erreur de modèle introuvable signifie que la valeur model ne correspond pas exactement à un modèle disponible. La casse et les suffixes comptent. Comparez votre valeur caractère par caractère avec la page de documentation du modèle.

3. Structure de la charge utile

400 provient généralement d'un corps de requête mal formé. Vérifiez que messages est un tableau, que chaque message contient role et content, et que le JSON est valide. Passer la charge utile par jq ou python -m json.tool avant l'envoi permet de détecter les erreurs de syntaxe.

4. Traitement de la réponse

Si la requête réussit mais que le script plante, le problème vient du code d'analyse et non de l'API. Journalisez le corps brut de la réponse avant de le découper, et vérifiez que le chemin que vous lisez existe réellement. L'image peut être renvoyée sous forme d'URL lors d'un appel et en base64 lors d'un autre ; branchez donc selon le contenu plutôt que de présumer.

5. Délais d'attente et nouvelles tentatives

La génération d'images peut être lente. En cas de délai d'attente, augmentez le timeout côté client et réessayez une fois. Évitez de réessayer sur les erreurs 4xx, car elles échoueront de la même manière.

Une habitude utile : conservez une copie d'une requête connue comme valide et comparez-y les requêtes en échec. La plupart des échecs ne tiennent qu'à un seul champ.

Envelopper dans un client réutilisable

Une fois l'appel fonctionnel, enveloppez-le dans une petite fonction afin que les changements de modèle et de paramètres soient centralisés. Cette enveloppe regroupe la recherche de la clé, les en-têtes et la gestion des erreurs :

import base64
import os

import requests

HIAPI_BASE = "https://api.hiapi.ai/v1"
DEFAULT_MODEL = "qwen-image-2.0-pro"


def generate_image(prompt: str, model: str = DEFAULT_MODEL) -> bytes:
    """Generate an image and return its raw bytes."""
    api_key = os.environ["HIAPI_API_KEY"]
    payload = {
        "model": model,
        "messages": [{"role": "user", "content": prompt}],
    }
    response = requests.post(
        f"{HIAPI_BASE}/chat/completions",
        headers={"Authorization": f"Bearer {api_key}"},
        json=payload,
        timeout=120,
    )
    response.raise_for_status()
    content = response.json()["choices"][0]["message"]["content"]

    if isinstance(content, str) and content.startswith("http"):
        return requests.get(content, timeout=60).content
    return base64.b64decode(content)

Le code d'appel se réduit à une ligne : open("out.png", "wb").write(generate_image("A ceramic mug on a wooden table")). Si vous passez ensuite à un autre modèle d'image ou ajoutez des paramètres, il suffit de modifier cette fonction. L'identifiant du modèle et tout détail de paramètre se trouvent sur la page du modèle ; vous pouvez d'abord consulter les détails du modèle qwen-image-2.0-pro avant de l'intégrer.

Commencez par l'appel curl, puis le script Python, et enfin l'enveloppe. Chaque étape valide une partie plus petite avant d'en construire une plus grande.

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