Tutoriel
Comment utiliser grok-imagine/text-to-image via l'API HiAPI : guide curl et Python
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 :
- 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é.
- Un outil capable de faire des requêtes HTTP. Pour le premier test,
curlsuffit. Pour Python, utilisezrequestsouhttpx; les deux sont abordés plus bas. - Un accès réseau à l'hôte de l'API HiAPI. Si vous êtes derrière un proxy d'entreprise, configurez
HTTPS_PROXYdans votre shell afin quecurlet 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 POSTavec un corps de requête JSON est la forme standard des points de terminaison de génération.modelsélectionne explicitementgrok-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.promptest 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 :
- Sujet — ce dont parle l'image, énoncé d'abord et avec précision. « Un cargo entrant dans le port » vaut mieux que « un bateau ».
- Style — le langage de rendu : photographie, vecteur plat, aquarelle, image de film. Un ou deux mots suffisent.
- 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 :
modelmal orthographié ou absent. Il doit valoirgrok-imagine/text-to-image.promptvide 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 →-
Tutoriel
Guide pratique de gpt-6.2-sol : 5 usages à forte valeur des modèles textuels en entreprise
-
Tutoriel
Guide pratique de gpt-6.2-astra : intégration et points clés de mise en œuvre pour 5 scénarios textuels à forte valeur
Liste de points de contrôle pour les développeurs, de la sélection des scénarios à la mise en œuvre technique
-
Tutoriel
Cas d'usage concrets de Tripo H3.1 : 5 usages à forte valeur et points clés de mise en œuvre
Du texte-vers-3D à la reconstruction multi-vues : choisir le bon mode et les bons paramètres selon le cas d'usage