Comment utiliser imagen-4.0 via l'API HiAPI : curl, Python et exemples de requêtes fonctionnelles

Les capacités d'imagen-4.0 mises à votre disposition par HiAPI

imagen-4.0 est un modèle de génération d'images à partir de texte : vous envoyez une invite en langage naturel et il renvoie une image générée. En tant que développeur d'intégration, ce qui compte vraiment n'est pas l'architecture du modèle, mais le contrat d'interface qui l'entoure. Via HiAPI, ce contrat est un point de terminaison HTTP — qui accepte du JSON et s'authentifie avec une clé bearer — exactement le même schéma que celui que vous connaissez déjà avec les appels de complétion de chat et d'embedding.

Les avantages concrets d'utiliser HiAPI plutôt que d'accéder directement au modèle :

• Un schéma d'authentification unifié. La même clé API fonctionne pour tous les modèles de la plateforme, vous n'avez donc pas à jongler entre les identifiants de plusieurs fournisseurs.
• Un format de requête unifié. Un corps JSON contenant l'identifiant du modèle et l'invite. Pas besoin d'apprendre la structure de requête propre à un SDK.
• Un retour synchrone. imagen-4.0 renvoie le résultat dans la même réponse HTTP, il n'est donc pas nécessaire de construire une boucle de polling ou un webhook dans les scénarios de base.

Ce guide vous accompagne de zéro jusqu'à une requête fonctionnelle en curl et en Python, puis explique comment lire la réponse et ce qu'il faut préparer avant de passer en production.

Obtenir une clé API et configurer l'authentification

Chaque appel à imagen-4.0 sur HiAPI s'authentifie avec un token bearer. Vous créez une clé API dans votre compte HiAPI, et cette clé est ensuite le seul identifiant nécessaire à la requête — pas d'ID de projet séparé, pas d'en-tête de signature.

Le principe qui évite la plupart des incidents : la clé doit être placée dans une variable d'environnement et ne jamais être commitée dans le code source. Une clé collée dans un script et poussée dans un dépôt de code est une clé que vous devrez faire tourner.

Configuration locale

Exportez la clé dans votre session shell :

export HIAPI_API_KEY="your-key-here"

Si vous voulez que la variable persiste, ajoutez cette ligne à votre fichier de configuration shell ; ou utilisez un fichier .env, ajoutez-le à .gitignore et chargez-le au démarrage de l'application.

Environnements déployés

Dans CI et en production, définissez HIAPI_API_KEY via le gestionnaire de secrets de la plateforme — en injectant la variable d'environnement au moment de l'exécution, plutôt qu'en intégrant le fichier dans l'image. Ainsi, le code de l'application est identique en local et en environnement déployé ; seule l'origine de la variable diffère.

En-têtes

Chaque requête porte :

Authorization: Bearer $HIAPI_API_KEY

Si vous voyez un 401, la première chose à vérifier est si l'en-tête est réellement envoyé et si la variable se résout en une valeur non vide. Un shell où la variable n'a jamais été exportée enverra tout de même Bearer , suivi de rien.

Comprendre la structure de la requête avant de l'envoyer

Le corps d'une requête imagen-4.0 est assez petit pour être mémorisé, et c'est précisément l'idée — une fois que vous avez compris sa structure, vous pouvez construire la requête dans n'importe quel langage, sans avoir à traduire un extrait de code copié-collé.

Il faut envoyer au minimum :

{
  "model": "imagen-4.0",
  "prompt": "A weathered lighthouse on a cliff at dusk, long exposure, muted colors"
}

Deux champs font l'essentiel du travail :

• model identifie le modèle qui traite la requête. C'est une chaîne, et c'est le même identifiant que celui utilisé par la plateforme partout où imagen-4.0 est listé. Une faute de frappe produit une réponse d'erreur, pas un repli silencieux.
• prompt est la description de l'image que vous voulez. Écrivez-le comme vous décririez la scène à une personne : sujet, cadre, style, lumière. Une invite concrète produit des résultats plus prévisibles qu'une invite d'un seul mot.

La requête est envoyée en POST, avec Content-Type: application/json, vers le point de terminaison de génération d'images de la plateforme. Le modèle peut avoir d'autres paramètres optionnels, mais le corps à deux champs ci-dessus est une requête complète et valide — partez de là et n'ajoutez des options que lorsque c'est nécessaire.

Comme le corps est du JSON pur, curl, Python, Node et tout outil disposant d'un client HTTP sont des citoyens de première classe. Les deux sections suivantes montrent la même requête écrite de deux manières.

Une requête curl fonctionnelle

Commencez depuis le terminal, où vous pouvez voir la réponse brute, sans aucune interférence de parsing.

curl -sS -X POST "$HIAPI_BASE_URL/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "imagen-4.0",
    "prompt": "A weathered lighthouse on a cliff at dusk, long exposure, muted colors"
  }'

Ligne par ligne :

• -sS masque la barre de progression mais affiche les erreurs, pour une sortie lisible sans masquer les échecs.
• -X POST définit la méthode. La génération d'images crée du contenu, donc c'est POST.
• L'URL est le point de terminaison de génération d'images de la plateforme, composé de votre URL de base plus le chemin. Conservez l'URL de base dans une variable pour que la même commande fonctionne dans différents environnements.
• Le premier en-tête porte votre clé bearer, lue depuis la variable d'environnement exportée précédemment.
• Content-Type: application/json indique au serveur comment analyser le corps.
• -d fournit le corps JSON. Les guillemets simples empêchent le shell d'interpréter les accolades et les guillemets ; le JSON est pris littéralement.

Pour inspecter la sortie, faites-la passer par un outil de formatage JSON :

curl -sS -X POST "$HIAPI_BASE_URL/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"imagen-4.0","prompt":"A weathered lighthouse on a cliff at dusk"}' \
  | python -m json.tool

Si la réponse contient une référence d'image, la requête a réussi. La section suivante la transforme en code applicatif.

La même requête en Python

L'appel curl se transpose directement. Le seul vrai choix est le client HTTP ; la bibliothèque standard urllib fonctionne partout, mais requests produit un code plus court et est déjà la dépendance de la plupart des bases de code.

Une fonction d'assistance réutilisable

import os
import requests

HIAPI_BASE_URL = os.environ.get("HIAPI_BASE_URL", "https://api.hiapi.ai/v1")


def generate_image(prompt: str, model: str = "imagen-4.0") -> dict:
    api_key = os.environ["HIAPI_API_KEY"]
    response = requests.post(
        f"{HIAPI_BASE_URL}/images/generations",
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        },
        json={"model": model, "prompt": prompt},
        timeout=120,
    )
    response.raise_for_status()
    return response.json()


result = generate_image("A weathered lighthouse on a cliff at dusk")
print(result)

Trois points méritent l'attention :

• os.environ["HIAPI_API_KEY"] lève immédiatement une KeyError si la variable manque, ce qui échoue vite et fort plutôt que d'envoyer un token vide.
• json= sérialise automatiquement le dictionnaire et définit le type de contenu, donc le comportement de la requête est identique à celui de la version curl.
• timeout=120 borne la durée de l'appel. La génération d'images prend plus de temps qu'une complétion de texte, d'où un délai d'attente généreux plutôt que l'absence de délai par défaut.

La fonction prend l'invite en paramètre et renvoie le JSON analysé, ce qui signifie que le reste de votre code n'a pas à toucher aux détails HTTP. Testez-la dans un REPL avant de la brancher à quoi que ce soit.

Lire la réponse synchrone et gérer les erreurs

imagen-4.0 répond de façon synchrone : l'image générée est renvoyée dans le corps de la même réponse HTTP. Aucun ID de tâche à interroger, aucune boucle de polling à écrire dans les scénarios de base — traitez cet appel comme n'importe quelle autre interaction requête-réponse.

Ce qui est renvoyé

Une réponse réussie est un objet JSON. Analysez-la avec response.json() en Python, ou faites passer la sortie curl par un outil de formatage JSON, puis localisez les données d'image dans la structure renvoyée — généralement une URL ou une charge d'image encodée, ainsi que des métadonnées sur la génération. Lisez une fois les noms de champs exacts dans une vraie réponse, puis écrivez votre code en conséquence.

Les problèmes à prévenir

Encapsulez l'appel et vérifiez le statut avant d'analyser :

try:
    result = generate_image("A weathered lighthouse on a cliff at dusk")
except requests.HTTPError as e:
    print("HTTP error:", e.response.status_code, e.response.text)
except requests.Timeout:
    print("Request timed out")

Modes d'échec à traiter explicitement :

• 401 — clé absente ou invalide. Corrigez la variable d'environnement, pas le code.
• 4xx en général — corps mal formé, identifiant de modèle incorrect ou invite refusée. Le corps de la réponse indique généralement lequel. Journalisez-le.
• 5xx — défaillance côté serveur. Ce sont ces erreurs qui méritent un nouvel essai avec backoff.
• Timeout — à traiter comme un résultat inconnu plutôt que comme un succès ; ne supposez pas que l'image a été générée.

En cas d'échec, journalisez toujours le code de statut et le corps de réponse tronqué. Déboguer sans ces informations revient à deviner.

De la première requête à la production

La requête fonctionne. Avant de passer à l'échelle, vérifiez chaque point :

• Configuration. L'URL de base et la clé API proviennent toutes deux de l'environnement. Aucun littéral dans le code source, aucune clé dans l'image.
• Délais d'attente. Chaque appel d'image a un délai d'attente. Sans délai, une requête bloquée peut occuper indéfiniment un processus de travail.
• Nouveaux essais. Ne réessayez que les 5xx et les timeouts, avec un backoff exponentiel plafonné. Ne réessayez jamais un 401 ni un 4xx dû à un corps mal formé — ils échoueront exactement de la même manière.
• Journalisation. Enregistrez le modèle, la longueur de l'invite, le code de statut et la latence pour chaque appel. Ne journalisez pas la clé, et si les invites peuvent contenir des données utilisateur, ne journalisez pas non plus l'invite complète.
• Conscience des coûts. La génération d'images est facturée sur la base des sorties produites, donc suivez le nombre d'images demandées par utilisateur ou par tâche, et fixez une limite au niveau applicatif. Pour les tarifs actuels, consultez le panneau de tarification de la plateforme, pas ce guide.
• Concurrence. Les appels d'image sont plus lents que les appels de texte. Dimensionnez le pool de processus de travail en conséquence, au lieu de supposer une latence de complétion de chat.

Une fois ces points réglés, la même fonction d'assistance generate_image s'utilise sans modification pour des tâches par lots, des fonctionnalités destinées aux utilisateurs et des outils internes. Pour plus de détails d'intégration, consultez la documentation de la plateforme.