Tutoriel
Comment appeler fibo-2.0/text-to-image via l'API HiAPI : curl et Python en pratique
Sur cette page
Ce que ce tutoriel construit
Il s'agit d'un guide pratique qui vous emmène de l'appel à fibo-2.0/text-to-image sur HiAPI jusqu'à l'obtention réelle d'une image. À la fin, vous disposerez de deux éléments immédiatement utilisables : une commande curl capable de générer une requête de génération d'image valide, et une petite fonction Python qui fait la même chose et renvoie le résultat pour un traitement ultérieur.
Nous avançons dans l'ordre où la plupart des développeurs travaillent réellement. D'abord, vérifier que l'environnement et les identifiants sont en place. Ensuite, lire le corps de la requête champ par champ pour que vous compreniez clairement ce que contrôle chaque partie. Puis envoyer l'appel avec curl pour prouver que l'endpoint, la clé et la charge utile concordent. Ce n'est qu'après que nous portons la même requête en Python, où le travail vraiment intéressant commence : analyser la réponse, gérer les échecs, l'encapsuler dans une fonction.
L'objectif n'est pas d'énumérer tous les paramètres possibles, mais de vous donner une forme de requête que vous comprenez parfaitement, afin que vous puissiez adapter le prompt, les dimensions de sortie et le code environnant à votre propre cas d'usage, sans deviner.
Avant d'envoyer la première requête
Trois conditions doivent être remplies avant le premier appel réussi.
Un compte HiAPI et une clé d'API
Les requêtes vers fibo-2.0/text-to-image nécessitent une authentification. Générez une clé d'API dans votre compte HiAPI et tenez-la à l'écart du contrôle de source. Les exemples ci-dessous lisent la clé depuis une variable d'environnement plutôt que de la coder en dur — faites-le dès le premier jour, car ajouter la gestion des clés après coup est fastidieux.
export HIAPI_API_KEY="your-api-key-here"
Un outil capable d'envoyer des requêtes HTTP
Pour la partie pratique avec curl, curl doit être présent sur votre machine. Il est fourni avec macOS et la plupart des distributions Linux ; sous Windows, il est aussi disponible dans les versions actuelles et dans Windows Terminal. Pour la partie Python, vous avez besoin de Python 3 et de la bibliothèque requests, le moyen le plus courant de lancer des appels HTTP depuis un script. Si ce n'est pas déjà installé :
pip install requests
Savoir ce que vous voulez générer
Préparez un prompt. Les modèles d'image réagissent fortement aux descriptions concrètes et explicites — sujet, style, éclairage et composition —, donc une seule ligne d'idée suffit généralement pour commencer les tests. Vous l'affinerez après avoir vu le premier résultat ; c'est une boucle normale.
Une fois ces trois éléments en place, tout le reste concerne le corps de la requête.
Analyser la requête champ par champ
Un appel à fibo-2.0/text-to-image est une requête POST avec un corps JSON. Le corps est petit : un prompt et des réglages qui façonnent la sortie. Plutôt que de mémoriser la charge utile complète, comprenez chaque champ afin de pouvoir le modifier en connaissance de cause.
L'identifiant du modèle
Le chemin de l'endpoint indique lui-même le modèle : fibo-2.0/text-to-image. Dans la plupart des cas, vous n'avez pas besoin de transmettre une chaîne de modèle supplémentaire — la route que vous appelez détermine quel modèle s'exécute. Si votre intégration prend en charge le routage via un endpoint partagé, placez le nom du modèle dans une constante de configuration afin de pouvoir le changer sans modifier le point d'appel.
Le prompt
C'est l'entrée centrale : la description textuelle de l'image que vous voulez. Traitez-la comme une spécification, pas comme un souhait. Nommer le sujet, le style visuel et la composition donne au modèle plus d'informations exploitables que des concepts abstraits. Placez le prompt dans une variable ou un fichier séparé pour pouvoir itérer rapidement sans réécrire le code de la requête.
Les réglages de sortie
Les requêtes d'image transportent généralement un petit ensemble de contrôles de sortie — le plus souvent la dimension ou le rapport d'aspect de l'image générée, et le nombre de résultats si vous en voulez plusieurs. Utilisez les noms de champs documentés dans la référence des modèles HiAPI pour fibo-2.0/text-to-image ; la charge utile d'exemple ci-dessous utilise ces noms canoniques. Si un réglage n'est pas documenté pour ce modèle, omettez-le plutôt que de deviner — les champs inconnus sont une source fréquente d'erreurs de validation.
Ce qu'il ne faut pas mettre dans le corps de la requête
Ne placez pas la clé d'API dans le corps JSON. L'authentification appartient aux en-têtes. Garder les identifiants hors de la charge utile signifie que le corps peut être journalisé et comparé en toute sécurité lors du débogage, ce que vous apprécierez dès que la première requête échouera.
Une requête curl fonctionnelle
Voici un appel complet. Remplacez le prompt par le vôtre et exécutez-le dans un shell où HIAPI_API_KEY est défini.
curl -X POST "https://api.hiapi.ai/v1/models/fibo-2.0/text-to-image" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "port paisible à l'aube, légère brume sur l'eau, composition large, style photographique",
"size": "1024x1024",
"n": 1
}'
Le rôle de chaque partie
-X POSTdéfinit la méthode HTTP. La génération d'image est une opération de création, donc POST, pas GET.- L'URL pointe vers la route
fibo-2.0/text-to-imagesur l'hôte de l'API HiAPI. Si votre compte utilise une URL de base régionale ou propre à un projet, remplacez cet hôte et conservez le chemin. Authorization: Bearer $HIAPI_API_KEYtransmet votre clé depuis l'environnement. Le shell développe la variable, donc la clé n'apparaît jamais comme chaîne littérale dans l'historique de vos commandes.Content-Type: application/jsonindique au serveur que le corps est du JSON. Sans cela, de nombreuses passerelles le rejettent avant même qu'il n'atteigne le modèle.-d '...'est le corps JSON : le prompt, la dimension demandée et le nombre d'images.
Vérifier le résultat
Exécutez la commande et examinez d'abord la sortie brute. Un appel réussi renvoie un document JSON décrivant l'image générée ; un appel échoué renvoie un objet d'erreur. Avant de construire quoi que ce soit par-dessus, assurez-vous de pouvoir distinguer les deux à l'œil nu. Si la réponse est volumineuse, traitez-la avec un outil de formatage comme jq pour rendre la structure lisible :
curl -s -X POST "https://api.hiapi.ai/v1/models/fibo-2.0/text-to-image" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt":"port paisible à l'aube","size":"1024x1024","n":1}' | jq .
Une fois l'appel manuel réussi, vous avez écarté les identifiants et la charge utile comme suspects. Tous les problèmes suivants se situent dans votre code.
Le même appel en Python
La version Python fait exactement ce que fait la commande shell, mais vous offre un endroit pour valider les entrées, réessayer et stocker les résultats. Gardez-la petite et explicite.
import os
import requests
API_URL = "https://api.hiapi.ai/v1/models/fibo-2.0/text-to-image"
def generate_image(prompt: str, size: str = "1024x1024", n: int = 1) -> dict:
api_key = os.environ["HIAPI_API_KEY"]
payload = {
"prompt": prompt,
"size": size,
"n": n,
}
response = requests.post(
API_URL,
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
},
json=payload,
timeout=60,
)
response.raise_for_status()
return response.json()
if __name__ == "__main__":
result = generate_image(
"port paisible à l'aube, légère brume sur l'eau, composition large, style photographique"
)
print(result)
Pourquoi l'écrire ainsi
- La clé est lue depuis l'environnement à l'intérieur de la fonction, donc si elle manque, l'appel échoue bruyamment au démarrage au lieu d'envoyer une requête non authentifiée.
json=payloadlaisserequestssérialiser le corps et définir correctement le type de contenu. Ne construisez pas de chaînes JSON à la main en Python ; cela introduit des erreurs de guillemets qui ne se révèlent qu'à l'exécution.timeout=60rend les échecs lents explicites. La génération d'image n'est pas instantanée, alors choisissez un délai d'attente que vous êtes prêt à attendre, mais fixez-en toujours un.raise_for_status()transforme les réponses 4xx et 5xx en exceptions. C'est cette ligne qui empêche un appel échoué d'être silencieusement traité comme un succès.- La fonction prend
prompt,sizeetnen paramètres, afin que le reste de votre programme puisse l'appeler comme n'importe quelle autre fonction de bibliothèque.
Exécutez ce fichier et vous devriez voir la même structure JSON que celle renvoyée par l'appel curl.
Lire la réponse et gérer les erreurs
Une réponse réussie vous donne un objet JSON décrivant la sortie générée. Le détail qui vous intéresse est l'image générée elle-même — généralement une URL ou une référence que vous pouvez télécharger ou stocker — ainsi que les métadonnées que l'API renvoie sur la requête. Analysez la réponse comme des données ; ne l'extrayez pas par manipulation de chaînes. Si la forme ne correspond pas à vos attentes lors de votre première inspection d'une réponse en direct, vérifiez la référence du modèle avant d'ajuster l'analyseur, car deviner les noms de champs est précisément la façon dont les intégrations se cassent silencieusement.
Détecter les échecs
Trois niveaux d'échec méritent d'être traités intentionnellement.
Erreurs de transport. La requête ne s'est jamais terminée : échec DNS, connexion réinitialisée, délai d'attente. En Python, elles se manifestent sous forme de requests.exceptions, et il est sûr de réessayer avec un backoff.
Codes d'état HTTP d'erreur. Le serveur a répondu mais a rejeté la requête. Un 401 signifie généralement que la clé est absente ou incorrecte ; une erreur de validation 4xx signifie généralement un nom de champ ou une valeur incorrecte ; un 429 signifie que vous envoyez trop vite ; un 5xx signifie qu'un problème est survenu côté serveur. raise_for_status() capture tout cela comme une seule exception, donc vérifiez le message dans le corps de la réponse avant de décider quoi faire.
Code 200 mais corps de réponse inattendu. C'est pourquoi vous validez la structure au lieu de la supposer. Vérifiez que les champs dont vous dépendez existent avant de les utiliser et, même si le code d'état est 200, traitez l'absence de référence d'image comme un échec.
try:
result = generate_image("port paisible à l'aube")
image = result.get("data", [{}])[0]
except requests.HTTPError as exc:
print("request failed:", exc.response.status_code, exc.response.text)
Une habitude importante : ne jamais avaler silencieusement les erreurs. Journalisez au minimum le code d'état et le corps de la réponse, car cette paire d'informations vous indique s'il faut corriger la charge utile ou attendre et réessayer.
Vers la production
Une fois qu'un appel unique fonctionne et que les échecs sont visibles, quelques petites habitudes permettent à l'intégration de tenir face au trafic réel.
Ne réessayer que ce qui est sûr à réessayer
Les erreurs de transport, les délais d'attente, les réponses 429 et 5xx méritent d'être réessayés avec un backoff exponentiel et une limite de tentatives. Les erreurs de validation et les 401 ne le méritent pas — réessayer une requête mal formée ne fait que consommer du quota. Distinguez clairement ces deux catégories dans votre gestion des erreurs.
Garder la configuration hors du code
Placez l'URL de base de l'API, le chemin du modèle, les dimensions par défaut et les délais d'attente dans la configuration plutôt que dispersés dans les fonctions. Lorsque vous passerez d'un environnement de test à un autre, ou que vous essaierez plus tard un modèle similaire, vous n'aurez qu'un seul endroit à modifier.
Journaliser requêtes et réponses, mais sans les clés
Journalisez les prompts, les paramètres, les codes d'état et les réponses tronquées. Ne journalisez jamais la clé d'API. C'est ainsi que vous pourrez répondre une semaine plus tard à la question « pourquoi cette image est-elle revenue incorrecte » sans avoir à reproduire le problème.
Valider les entrées avant l'envoi
Vérifiez que le prompt n'est pas vide et reste dans une longueur raisonnable, et que size et n correspondent aux valeurs documentées du modèle. Détecter une valeur erronée localement est plus rapide et moins coûteux qu'un aller-retour réseau.
Stocker les résultats, ne pas seulement les afficher
Les références d'image générées peuvent être temporaires. Dans le cadre du même job, téléchargez ou copiez la sortie dans votre propre stockage et enregistrez quel prompt et quels paramètres l'ont produite. Cette trace rend la régénération et l'audit possibles.
En encapsulant fibo-2.0/text-to-image derrière la petite fonction generate_image de ce tutoriel, vous faites dépendre le reste de votre application de cette fonction plutôt que d'appels HTTP bruts. Lorsque vous serez prêt à faire varier les prompts à grande échelle, la référence des modèles HiAPI est l'endroit où vérifier les paramètres pris en charge avant d'étendre l'interface.
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