Comment utiliser imagen-4.0-fast via l'API HiAPI : guide curl et Python

Les axes d'optimisation d'imagen-4.0-fast

imagen-4.0-fast est le niveau orienté faible latence de la série imagen-4.0 : il vise une réponse rapide aux requêtes de génération d'images tout en conservant la même structure de requête et de réponse que les autres modèles de la série. En pratique, il faut choisir ce niveau lorsque les images doivent apparaître instantanément pendant l'interaction utilisateur — par exemple des vignettes de brouillon, des aperçus destinés à être affinés par l'utilisateur, des visuels nécessaires à une mise en page en temps réel — plutôt que dans un traitement par lots hors ligne (où le temps réel importe peu).

Une façon efficace de penser le choix du modèle consiste à distinguer le budget d'interaction du plafond de qualité. Lorsque le budget d'interaction est serré et qu'une image « suffisamment bonne » débloque l'étape suivante, le niveau rapide l'emporte. Lorsque l'image est elle-même le livrable, le niveau de qualité supérieure l'emporte. Comme imagen-4.0-fast partage la même interface HiAPI que les autres modèles d'image, le changement de niveau ultérieur ne demande qu'une modification de configuration, sans réécriture de code — vous pouvez donc commencer par le niveau rapide, mesurer si la qualité de sortie atteint le standard du produit, puis envisager de faire monter certains cas d'usage d'un cran.

Un autre aspect de l'optimisation du niveau rapide est la prévisibilité sous charge. Une durée de génération courte signifie une connexion occupée moins longtemps, ce qui rend le comportement du budget de concurrence plus proche du linéaire : avant d'atteindre la limite de débit du compte, doubler les workers apporte à peu près le double de débit, au lieu d'expirer en cours de génération. La discussion ultérieure sur les timeouts et la concurrence repose sur cette caractéristique.

Si votre cas d'usage implique un parcours utilisateur en plusieurs étapes, du traitement par lots, ou tout scénario où une requête peut être retentée, le niveau rapide est le choix par défaut le plus sûr — vous pouvez vous permettre une tentative supplémentaire tout en restant dans la fenêtre de patience humaine.

Prérequis et configuration de l'API

Avant le premier appel, quatre éléments sont nécessaires.

1. Compte HiAPI et clé d'API

Toute génération d'images passe par l'API unifiée HiAPI. Créez une clé d'API dans la console HiAPI et stockez-la dans une variable d'environnement plutôt que dans le code source :

export HIAPI_API_KEY="your_key_here"

Ne validez jamais la clé. Si votre code s'exécute dans une CI ou un conteneur, injectez cette variable à l'exécution via un gestionnaire de secrets.

2. URL de base et identifiant de modèle

Conservez deux constantes dans un module de configuration afin que chaque requête du code pointe au même endroit :

HIAPI_BASE_URL = "https://api.hiapi.ai"
HIAPI_IMAGE_MODEL = "imagen-4.0-fast"

L'identifiant de modèle sert à sélectionner imagen-4.0-fast dans la charge utile de la requête. Traitez-le comme une donnée, et non comme une chaîne codée en dur dispersée dans les fichiers.

3. Un client HTTP de confiance

En Python, httpx et requests conviennent tous deux ; httpx offre un objet de timeout plus clair. Pour le travail en shell, curl suffit et constitue le moyen le plus rapide d'isoler si le problème vient de votre code ou de la requête elle-même.

4. Un outil de test minimal

Déterminez à l'avance où seront déposées les sorties générées — écrire un fichier sur disque convient pour un test de fumée, mais le code de production devrait diffuser ou stocker de manière réfléchie, plutôt que de garder des charges utiles volumineuses en mémoire.

Deux habitudes de configuration portent rapidement leurs fruits. Premièrement, centralisez l'authentification dans une fonction utilitaire qui ajoute l'en-tête Authorization, afin que la rotation de la clé n'exige qu'une modification à un seul endroit. Deuxièmement, conservez un indicateur DEBUG qui vous permette d'afficher l'ID de requête et la durée sans modifier la charge utile. Lors d'un incident à deux heures du matin, ces deux habitudes font la différence entre une correction en cinq minutes et une heure de conjectures.

Effectuer une requête fonctionnelle avec curl

Voici un appel curl complet et exécutable. Il génère une image à partir d'un prompt textuel :

curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "imagen-4.0-fast",
    "prompt": "a quiet harbor at dawn, soft mist over wooden docks, photographic",
    "n": 1,
    "size": "1024x1024"
  }'

Détail champ par champ :

• -sS masque la barre de progression mais affiche tout de même les erreurs. En débogage, ajoutez -i pour voir les en-têtes de réponse, qui contiennent souvent l'ID de requête, utile à citer lors d'une demande d'aide.
• -X POST combiné à l'en-tête Content-Type: application/json fait de la charge utile une requête structurée, plutôt qu'un corps opaque.
• Authorization: Bearer $HIAPI_API_KEY est l'unique mécanisme d'authentification. La clé est lue depuis la variable d'environnement, de sorte que, tant que vous la définissez dans la session, elle n'apparaît pas en clair dans l'historique du shell.
• model sélectionne imagen-4.0-fast sur le point de terminaison d'images HiAPI. L'omettre risque de donner un modèle par défaut différent — spécifiez-le toujours explicitement.
• prompt est le seul champ de contenu obligatoire. Restez descriptif sans écrire une encyclopédie ; un prompt trop long consomme des tokens et, au-delà d'un certain point, améliore rarement la sortie du niveau rapide.
• n contrôle le nombre d'images renvoyées par la requête. Commencez par 1 pendant l'intégration.
• size est la demande de résolution de sortie. La section 5 explique comment la choisir.

Exécutez-la une première fois et inspectez le corps de la réponse avant d'écrire le moindre code Python. Si curl réussit, toute défaillance ultérieure vient du code client. Si curl échoue, le problème vient de la clé, de la charge utile ou du compte — et vous avez déjà éliminé la moitié du champ d'investigation.

Effectuer la même requête en Python

Voici un client Python minimal, correspondant champ par champ à l'appel curl, avec une gestion d'erreurs autour de la couche HTTP :

import os
import httpx

HIAPI_BASE_URL = "https://api.hiapi.ai"
HIAPI_IMAGE_MODEL = "imagen-4.0-fast"

def generate_image(prompt: str, size: str = "1024x1024") -> dict:
    api_key = os.environ["HIAPI_API_KEY"]  # fail fast if unset
    payload = {
        "model": HIAPI_IMAGE_MODEL,
        "prompt": prompt,
        "n": 1,
        "size": size,
    }
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    }
    with httpx.Client(timeout=httpx.Timeout(60.0, connect=10.0)) as client:
        response = client.post(
            f"{HIAPI_BASE_URL}/v1/images/generations",
            json=payload,
            headers=headers,
        )
    if response.status_code == 401:
        raise RuntimeError("HiAPI rejected the API key")
    if response.status_code == 429:
        raise RuntimeError("Rate limited; back off and retry")
    response.raise_for_status()
    return response.json()

if __name__ == "__main__":
    result = generate_image("a quiet harbor at dawn, soft mist over wooden docks, photographic")
    print(result)

Ce fragment contient plusieurs choix délibérés :

• os.environ["HIAPI_API_KEY"] lève immédiatement une KeyError si la variable manque, ce qui vaut mieux que d'envoyer une requête non authentifiée et de confondre le 401 avec un problème de clé.
• Des timeouts explicites — le timeout de connexion et le timeout de lecture sont définis séparément. Le timeout de lecture est le plus critique pour la génération d'images, car le serveur maintient la connexion pendant la génération.
• Un traitement par branche selon le code de statut, avant raise_for_status(). Les codes 401 et 429 exigent des réponses très différentes du code ; les fusionner en une seule exception rend les nouvelles tentatives hasardeuses.
• Le gestionnaire de contexte Client garantit une fermeture déterministe des connexions. Dans un service à longue durée de vie, créez un client au démarrage et réutilisez-le — la réutilisation des connexions est importante pour le débit.

Le corps de la réponse contient les références des images générées et des métadonnées. Enregistrez le corps complet de la réponse lors des premiers appels pendant l'intégration, afin de savoir exactement quels noms de champs votre code utilise.

Choix des paramètres et de la résolution

La gestion des paramètres d'imagen-4.0-fast gagne à rester simple et explicite. Gardez la charge utile sous forme de dictionnaire construit par une fonction unique, et validez-la avant l'envoi plutôt qu'après l'échec.

Le prompt

Le prompt est le paramètre au plus fort levier, et aussi le plus facile à surconcevoir. Décrivez dans l'ordre le sujet, la scène, le style. Évitez d'empiler des termes de style contradictoires ; le niveau rapide les interprétera comme une moyenne, et non comme le compromis que vous contrôlez. Si vous générez plusieurs fois le même prompt, mettez le résultat en cache côté serveur plutôt que de le redemander.

n

Demander plusieurs images en un seul appel est pratique pour un sélecteur destiné à l'utilisateur, mais cela multiplie le travail d'une requête unique, prolongeant ainsi l'occupation de la connexion. Gardez n à 1 pendant l'intégration ; ne l'augmentez qu'après avoir mesuré la latence de bout en bout une fois activé.

size

Le paramètre de résolution est l'endroit où le coût et la latence s'accumulent discrètement. Une sortie plus grande implique plus de travail de génération et un corps de réponse plus volumineux. Choisissez la plus petite résolution qui satisfait le contexte d'affichage — un emplacement de vignette n'a pas besoin des dimensions d'une image principale. Découplez la taille de génération de la taille d'affichage, et laissez votre pipeline d'images effectuer ensuite un agrandissement ou une réduction ; cela garde les requêtes prévisibles et facilite, plus tard, l'ajustement de la qualité en fonction de la latence sans modifier la logique du prompt.

Déterminisme et reproductibilité

Journalisez chaque paramètre envoyé avec la sortie, en indexant par ID de requête. Quand quelqu'un demande pourquoi une image diffère de celle de la semaine dernière, la charge utile stockée répond en quelques secondes. Si vous construisez la charge utile en fusionnant les entrées utilisateur avec des valeurs par défaut, validez le résultat fusionné comme un tout — les remplacements partiels sont une source fréquente de requêtes malformées.

Une règle pratique : la charge utile doit être petite, entièrement explicite et reproductible à partir des journaux. Tout ce qui ne peut pas être reconstruit à partir des journaux est un paramètre que vous finirez par regretter d'avoir ajouté.

Gérer les timeouts et la concurrence

Comme imagen-4.0-fast conserve des temps de génération courts, la plupart des problèmes de fiabilité se situent côté client : timeouts réglés trop bas, nouvelles tentatives déclenchées à tort, ou parallélisme trop élevé par rapport aux limites du compte.

Timeouts

Définissez deux valeurs, pas une. Un timeout de connexion court capture rapidement les problèmes réseau et DNS ; un timeout de lecture plus long absorbe le temps de génération plus le transfert. Le timeout de lecture doit être choisi d'après la latence p95 observée dans votre environnement, majorée d'une marge, et non au hasard. Relancer une requête expirée alors que le serveur travaille encore gaspille de la capacité — donc si vous retentez vraiment, traitez la nouvelle tentative comme un nouvel essai doté de son propre budget, sans supposer que le premier était gratuit.

Nouvelles tentatives

Ne retentez que ce qui peut l'être sans risque : erreurs de connexion et réponses 5xx. Ne retentez jamais un 4xx — une charge utile malformée échouera de la même manière à chaque fois. Utilisez un backoff exponentiel avec gigue et limitez le nombre total de tentatives. Une structure utile consiste en trois tentatives, avec des délais d'environ 1 s, 2 s et 4 s, randomisés, ce qui répartit la charge lorsque de nombreux clients échouent simultanément.

Concurrence

Pour le traitement par lots, utilisez un pool de workers borné, et non un asyncio.gather non borné. Chaque requête en cours occupe une connexion et consomme le budget de débit de votre compte. Commencez par un petit pool — quelques requêtes concurrentes — mesurez le débit, et augmentez jusqu'à ce que la latence ne s'améliore plus ou que des 429 apparaissent. Les temps de génération courts du niveau rapide sont ici un avantage : comme chaque requête se termine vite, un pool modéré suffit à maintenir un débit élevé sans garder longtemps les connexions ouvertes.

Contre-pression

Lorsque vous recevez un 429, la bonne réponse est de ralentir, pas de retenter immédiatement. Ajoutez un court délai selon le modèle de backoff décrit ci-dessus, et envisagez de réduire temporairement la taille du pool. Journalisez le niveau de concurrence au moment du 429 — ce chiffre est votre plafond effectif.

Déboguer les échecs de requête courants

Traitez les échecs dans l'ordre qui élimine le plus d'incertitude à chaque étape : reproduisez d'abord avec curl, puis passez au client.

401 Unauthorized

Clé manquante, mal formée ou non envoyée comme jeton Bearer. Vérifiez directement l'en-tête Authorization, confirmez que la variable d'environnement est bien renseignée dans le processus qui effectue l'appel (les conteneurs et les runners CI diffèrent de votre shell), et assurez-vous qu'aucune guillemet superflue ni espace de fin n'entoure la valeur. Si curl fonctionne avec la clé littérale mais que votre application échoue, le problème vient certainement du chargement de l'environnement.

400 Bad Request

Charge utile malformée ou valeur de paramètre invalide. Reproduisez avec le JSON exact que votre client envoie réellement — journalisez la charge utile sérialisée, et non le dictionnaire en mémoire — et comparez-la à l'exemple curl qui fonctionne. Causes fréquentes : en-tête Content-Type manquant, faute de frappe dans model, champs numériques envoyés sous forme de chaînes, et champs hérités d'une ancienne forme d'API.

422 / erreurs de validation

Le champ existe mais sort de la plage autorisée — souvent n ou size défini à une valeur que le modèle n'accepte pas. Réduisez la charge utile aux champs strictement nécessaires, confirmez qu'elle réussit, puis rajoutez les paramètres un à un.

429 Débit limité ou quota épuisé

Vous envoyez plus de requêtes, ou plus de requêtes simultanées, que le compte ne l'autorise. Confirmez-le avec les journaux de concurrence, réduisez la taille du pool et vérifiez que le modèle de backoff est réellement appliqué. Si cela persiste à faible volume, vérifiez si un autre processus partage la même clé.

5xx et timeouts

Problème côté serveur ou réseau. Retentez une ou deux fois avec backoff ; si l'échec est reproductible pour une charge utile donnée, capturez l'ID de requête dans les en-têtes de réponse et la charge utile exacte — c'est ce qui rend une escalade productive.

Une habitude générale

Conservez pour chaque incident de production une reproduction curl avec --verbose. Passer de l'erreur applicative à une seule commande curl copiable réduit le débogage à la requête elle-même. À ce stade, l'utilisation d'imagen-4.0-fast via l'API HiAPI devient prévisible.