Blog

Tutoriel

Comment utiliser grok-imagine/text-to-image via l'API HiAPI : guide curl et Python

Nov 12, 2026
Illustration de couverture en papier superposé, tons crème et graphite, avec une unique feuille terracotta décalée en léger relief.
Sur cette page

Ce que grok-imagine/text-to-image vous apporte

grok-imagine/text-to-image est un point de terminaison de génération d'images texte-vers-image exposé via HiAPI : vous envoyez en JSON, par HTTP, un prompt et quelques paramètres de génération, puis vous recevez une image. C'est tout le contrat. Aucun SDK à installer, aucune session à initialiser, aucune tâche d'arrière-plan à interroger pour voir votre première image.

Sa place dans un flux de travail de développeur :

  • Prototypage. Vous passez d'une idée à une image rendue en une seule commande de terminal, ce qui vous permet de tester rapidement vos idées de prompts.
  • Pipelines de contenu. Comme il s'agit d'un simple appel HTTP, vous pouvez l'appeler depuis un service backend, un worker de file d'attente ou un script de build comme n'importe quelle autre API.
  • Fonctionnalités produit. La génération d'images destinée aux utilisateurs implique généralement un traitement prévisible des requêtes/réponses, des erreurs structurées et des tentatives. Un point de terminaison sans état convient parfaitement à ces trois aspects.

Ce que ce point de terminaison n'est pas : il ne stocke pas vos prompts, ne gère pas une bibliothèque d'images générées et ne remplace pas votre propre orchestration. La requête vous appartient, la sortie vous appartient, et la destination des octets vous appartient aussi.

Ce guide privilégie d'abord le fonctionnement de la requête, puis sa fiabilité. Que vous appeliez avec curl ou Python, le schéma est identique, car il s'agit dans les deux cas de la même requête HTTP authentifiée. Commencez par le minimum viable, confirmez l'aller-retour réussi, puis ajoutez de la complexité.

Prérequis et authentification

Avant votre premier appel, assurez-vous de disposer des éléments suivants :

  1. Un compte HiAPI et une clé API. Traitez la clé comme un secret : chargez-la depuis une variable d'environnement, ne l'inscrivez jamais en dur dans un script susceptible d'être commité.
  2. Un outil capable de faire des requêtes HTTP. Pour le premier test, curl suffit. Pour Python, utilisez requests ou httpx ; les deux sont abordés plus bas.
  3. Un accès réseau à l'hôte de l'API HiAPI. Si vous êtes derrière un proxy d'entreprise, configurez HTTPS_PROXY dans votre shell afin que curl et Python puissent le lire.

La clé est transmise sous forme de jeton bearer via l'en-tête Authorization :

export HIAPI_API_KEY="your-key-here"

Ensuite, chaque requête transporte :

Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json

Deux habitudes à prendre immédiatement :

  • Ne laissez pas la clé apparaître dans l'URL. Aucune partie de la requête ne doit placer d'identifiants dans la chaîne de requête, car celle-ci finira dans les journaux et l'historique du shell.
  • Une clé par environnement. Les clés de développement et de production doivent être des valeurs distinctes, afin de pouvoir en révoquer une sans impacter l'autre.

Si vous n'avez pas encore généré de clé, créez-en une dans le tableau de bord HiAPI et stockez-la dans votre gestionnaire de secrets ou dans un fichier .env local exclu du contrôle de version. Une fois que echo $HIAPI_API_KEY affiche la valeur, vous pouvez envoyer votre première requête.

Requête minimale fonctionnelle en curl

L'appel utile minimal envoie uniquement l'identifiant du modèle et le prompt. Tout le reste a des valeurs par défaut, donc ne vous précipitez pas sur le réglage des paramètres avant d'avoir vu une image revenir.

curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine/text-to-image",
    "prompt": "a lighthouse on a rocky coast at dusk, calm sea, soft overcast light"
  }'

Le rôle de chaque partie :

  • -X POST avec un corps de requête JSON est la forme standard des points de terminaison de génération.
  • model sélectionne explicitement grok-imagine/text-to-image. Figez le nom du modèle dans vos scripts plutôt que de vous fier aux valeurs par défaut, afin qu'un changement de défaut ne modifie pas silencieusement vos sorties.
  • prompt est la seule entrée de contenu. Pour le premier test, gardez-le sous forme d'une phrase claire.

Une réponse réussie renvoie du JSON contenant l'image générée, généralement une URL ou une charge base64, selon le format de réponse que vous demandez. Avant d'écrire le moindre code d'analyse, lisez la réponse avec un formateur JSON. Si vous consultez la sortie dans un terminal, un passage par python -m json.tool rend la structure plus lisible.

Une fois que cela fonctionne, enregistrez la réponse brute dans un fichier afin de disposer d'une référence connue et valide :

curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json \
  -o response.json

En plaçant le corps de la requête dans request.json, vous pouvez modifier le prompt sans vous battre avec les guillemets du shell, ce qui compte particulièrement lorsque le prompt s'allonge ou contient de la ponctuation.

La même requête en Python

La version Python est le même appel HTTP, mais avec une meilleure expérience : un dictionnaire au lieu de guillemets imbriqués, et un traitement direct des octets de l'image.

import os
import requests

api_key = os.environ["HIAPI_API_KEY"]
base_url = os.environ["HIAPI_BASE_URL"]

payload = {
    "model": "grok-imagine/text-to-image",
    "prompt": "a lighthouse on a rocky coast at dusk, calm sea, soft overcast light",
}

response = requests.post(
    f"{base_url}/v1/images/generations",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=120,
)
response.raise_for_status()
data = response.json()
print(data)

Deux détails méritent d'être soulignés. Premièrement, timeout=120 : la génération d'images n'est pas instantanée, et une requête sans délai d'attente laissera un worker suspendu indéfiniment si l'amont se bloque. Deuxièmement, appelez raise_for_status() avant l'analyse, afin que le corps d'une réponse d'erreur ne soit pas pris à tort pour une réponse d'image réussie.

Pour enregistrer l'image, gérez les deux formes de réponse :

item = data["data"][0]

if item.get("b64_json"):
    import base64
    image_bytes = base64.b64decode(item["b64_json"])
else:
    image_bytes = requests.get(item["url"], timeout=60).content

with open("output.png", "wb") as f:
    f.write(image_bytes)

Si vous préférez un ensemble de dépendances unique, httpx s'utilise de la même manière, avec httpx.post(..., json=payload). L'essentiel est que le corps et les en-têtes de la requête soient strictement identiques à l'exemple curl : c'est cette cohérence qui rend les deux exemples interchangeables et le débogage prévisible.

Structurer les prompts pour le rapport d'aspect

Les sorties panoramiques échouent d'une manière spécifique : le modèle dispose de beaucoup d'espace horizontal à remplir, il répète donc des éléments ou fait flotter un petit sujet dans un cadre vide. Vous résolvez cela par la structure du prompt, pas en empilant des adjectifs.

Utilisez un squelette en trois parties :

  1. Sujet — ce dont parle l'image, énoncé d'abord et avec précision. « Un cargo entrant dans le port » vaut mieux que « un bateau ».
  2. Style — le langage de rendu : photographie, vecteur plat, aquarelle, image de film. Un ou deux mots suffisent.
  3. Composition — comment le cadre est organisé ; c'est ici que se joue le succès d'un rapport panoramique.

Pour la composition, nommez explicitement la structure horizontale :

  • Indiquez un ordre de lecture de gauche à droite ou panoramique : « plan large, sujet dans le tiers droit, ciel dégagé à gauche ».
  • Décrivez le premier plan, le plan moyen et l'arrière-plan comme des bandes distinctes, car une image panoramique se lit naturellement par couches.
  • Précisez ce qui remplit les bords : « grues portuaires à l'extrême gauche, eaux ouvertes à l'extrême droite ». Les bords sont les premières zones à se vider dans une image panoramique.
  • Évitez les prompts qui suggèrent une composition portrait ou carrée — visages en gros plan, objet unique centré — et attendez-vous à ce qu'ils soient étirés ou complétés par des bandes noires.

Lorsque vous définissez un paramètre de rapport d'aspect pour un format panoramique, modifiez le prompt en même temps. Un prompt écrit pour un cadre carré produira un concept carré sur une toile large. Réécrivez-le pour décrire une scène avec une distance horizontale : une ligne d'horizon, une rue, des rangées d'objets, un groupe réparti dans une pièce.

Ne changez qu'une variable à la fois. Figez le rapport d'aspect et modifiez la formulation ; puis figez la formulation et modifiez le ratio. Consignez les deux avec la sortie, afin de pouvoir juger quel changement a réellement aidé.

Gérer les erreurs et les codes de réponse

Lisez d'abord le code de statut, puis le corps de la réponse. Chaque échec courant pointe vers un correctif différent ; les confondre fait perdre du temps.

401 Unauthorized

Clé absente, mal formée ou révoquée. Vérifiez que l'en-tête est bien Authorization: Bearer <key>, que la variable d'environnement est réellement développée (affichez sa longueur, pas sa valeur), et que vous n'avez pas envoyé par erreur une clé d'un autre environnement.

400 Bad Request

Votre JSON est un HTTP valide, mais invalide pour ce point de terminaison. Suspects courants :

  • model mal orthographié ou absent. Il doit valoir grok-imagine/text-to-image.
  • prompt vide ou absent.
  • Un paramètre du mauvais type — une chaîne là où un nombre est attendu, ou inversement.
  • Le corps de la requête n'est pas du JSON valide, souvent à cause de problèmes de guillemets shell dans curl. Déplacez le corps dans un fichier et utilisez -d @request.json.

Lisez le corps du message d'erreur ; il indique généralement le champ problématique.

429 Too Many Requests

Vous envoyez des requêtes plus vite que votre quota. Le correctif est côté client : backoff, file d'attente, nouvelles tentatives. Ne resserrez pas la boucle de réessai parce que vous recevez un 429 — cela aggravera la situation.

Erreurs serveur 5xx

Ce sont des conditions transitoires ou amont. Réessayez après un délai, et si l'échec persiste après plusieurs tentatives, capturez la charge utile de la requête et le corps de la réponse à des fins de diagnostic plutôt que de réessayer indéfiniment.

Délais d'attente et erreurs de connexion

Ce ne sont pas des codes de statut HTTP du tout, mais ce sont les échecs les plus courants en pratique. Si requests lève un délai de connexion, la requête a peut-être déjà été traitée. Avant d'écrire une boucle de réessai, décidez pour votre cas d'usage si un délai d'attente signifie « réessayer » ou « abandonner ».

Réglage et nouvelles tentatives en production

Une fois la requête de base fonctionnelle, réglez par petits pas : d'abord la formulation du prompt, puis le rapport d'aspect, puis les autres paramètres, en comparant les sorties côte à côte. Conservez chaque charge utile de requête avec sa sortie afin que les résultats restent reproductibles.

Un wrapper de production fait trois choses : ne réessayer que les échecs qui le méritent, journaliser suffisamment pour déboguer, et échouer bruyamment en cas d'abandon.

import time
import requests

def generate(payload, max_attempts=4):
    for attempt in range(1, max_attempts + 1):
        try:
            r = requests.post(
                f"{base_url}/v1/images/generations",
                headers=headers,
                json=payload,
                timeout=120,
            )
        except requests.RequestException as exc:
            log.warning("request failed attempt=%d err=%s", attempt, exc)
            time.sleep(2 ** attempt)
            continue

        if r.status_code == 429 or r.status_code >= 500:
            log.warning("retryable status=%d attempt=%d", r.status_code, attempt)
            time.sleep(2 ** attempt)
            continue

        if r.status_code >= 400:
            raise RuntimeError(f"{r.status_code}: {r.text[:500]}")

        return r.json()

    raise RuntimeError("exhausted retries")

Remarques sur ce schéma :

  • Backoff exponentiel plafonné (2 ** attempt) évite qu'un client limité en débit ne martèle le point de terminaison de manière répétée. Si vous exécutez de nombreux workers, ajoutez de la gigue.
  • Ne réessayez que les 429, les 5xx et les erreurs réseau. Un 400 ou un 401 échouera de la même manière à chaque tentative.
  • Journalisez le nombre de tentatives et le statut, jamais la clé API, et ne journalisez jamais le prompt complet s'il peut contenir des données utilisateur.
  • Limitez le temps total. Une boucle de réessai sans plafond transforme une requête lente en worker bloqué.

Mesurez vos propres latences et taux de succès plutôt que de les supposer ; ces deux chiffres vous indiquent s'il vous faut plus de parallélisme ou plus de backoff. Commencez par la requête minimale de ce guide, enveloppez-la dans la fonction utilitaire ci-dessus, puis itérez à partir de là.

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