Tutoriel
Comment appeler fibo-2.0/image-to-image via l'API HiAPI : pratique avec curl et Python
Sur cette page
La place de fibo-2.0/image-to-image dans le pipeline
Les modèles texte-vers-image partent d'un prompt ; les modèles image-vers-image partent d'une image que vous possédez déjà. Cet écart paraît minime, mais il détermine la position du modèle dans le pipeline : fibo-2.0/image-to-image n'est plus la première étape qui produit des assets, mais l'étape d'édition qui transforme une image existante.
Le workflow typique est le suivant : vous obtenez ou générez une image de base, vous l'envoyez à fibo-2.0/image-to-image avec une instruction décrivant la modification souhaitée, puis vous transmettez le résultat aux étapes suivantes — validation, composition, stockage ou un autre appel de modèle. Comme le modèle reçoit à la fois l'image d'entrée et le prompt, il peut redessiner le style, ajuster ou transformer la partie que vous décrivez tout en préservant la composition, la position du sujet et la structure d'ensemble.
Quand choisir image-vers-image plutôt que texte-vers-image
Choisissez image-vers-image lorsque la sortie doit conserver un lien identifiable avec une image existante : redessiner le style d'une photo en préservant le sujet, ajuster l'éclairage ou l'étalonnage des couleurs, générer des variantes d'un asset déjà validé, ou nettoyer une base brute avant l'usage final. Si vous n'avez pas d'image de départ mais seulement une description, choisissez texte-vers-image.
Ce que cette interface exige de vous
Cet appel est une soumission de tâche : vous envoyez l'image d'entrée, le prompt et les paramètres que vous voulez contrôler, et l'API renvoie une tâche traçable. Considérez cette interface comme une étape bien définie au sein d'une chaîne plus vaste, et non comme une application d'édition complète — la préparation de l'image d'entrée et le traitement du résultat vous incombent.
Comme la requête est intrinsèquement asynchrone, la conception de l'intégration doit s'articuler autour de cela : soumettre, conserver l'identifiant de tâche, interroger jusqu'à l'achèvement, puis récupérer la référence de sortie. Le reste de ce guide sert précisément à construire ce flux.
Préparer avant d'envoyer la requête
Trois choses sont nécessaires avant le premier appel : les identifiants, une bonne compréhension de la forme de l'interface, et une image d'entrée préparée.
Identifiants
Toutes les requêtes envoyées à l'API HiAPI sont authentifiées par une clé API. La clé doit rester côté serveur — ne l'intégrez jamais dans du code navigateur et ne la commitez jamais dans un dépôt. La méthode la plus propre consiste à la lire depuis une variable d'environnement, pour que le même code fonctionne en local comme en environnement déployé :
export HIAPI_API_KEY="your-api-key"
Si vous n'avez pas encore de clé, créez-la d'abord dans la console de votre compte HiAPI, puis poursuivez.
Forme de l'interface
Ce modèle est identifié dans l'API HiAPI par fibo-2.0/image-to-image. Tous les appels de modèle partagent la même URL de base et les mêmes conventions de requête, ce qui signifie qu'une fois que vous avez un appel fonctionnel, passer à un autre modèle revient principalement à changer l'identifiant du modèle et les champs du payload.
Préparer l'image d'entrée
Une requête image-vers-image a besoin d'une vraie image, et non d'une URL dont vous espérez qu'elle soit interprétée. Décidez à l'avance comment la fournir : en tant que fichier local téléversé avec la requête, ou en tant que référence acceptée par l'API ; et vérifiez que le format fonctionne avant d'écrire le code applicatif. Les deux échecs les plus fréquents lors d'une première requête sont : envoyer un chemin qui n'existe que sur votre ordinateur portable, et envoyer un fichier dans un format que l'interface n'accepte pas.
Checklist pratique avant de construire l'appel :
- L'image est un vrai fichier que votre langage peut lire.
- Le prompt décrit l'édition souhaitée en langage naturel, sans se limiter à une accumulation de mots-clés.
- Vous savez quels paramètres transmettre et lesquels laisser par défaut.
- Votre clé API est accessible dans l'environnement qui émet la requête.
Une fois ces points réglés, passez à la requête elle-même.
Décortiquer une requête curl fonctionnelle ligne par ligne
Commencez par curl. Il élimine toute abstraction entre vous et la requête HTTP ; en cas d'erreur, vous savez que le problème vient de la requête et non d'une bibliothèque cliente.
curl -X POST "https://api.hiapi.ai/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "fibo-2.0/image-to-image",
"prompt": "transforme la scène en une illustration aquarelle douce, conserve le sujet et le cadrage",
"image": "BASE64_ENCODED_IMAGE_OR_ACCEPTED_REFERENCE",
"n": 1
}'
Voici le rôle de chaque partie.
La ligne de requête
-X POST définit la méthode. L'URL est l'adresse de base de l'API HiAPI suivie du chemin de génération d'image. Placez l'adresse de base dans une variable ou une valeur de configuration pour éviter de la coder en dur à plusieurs endroits : une future modification ne nécessitera qu'une seule édition.
Les en-têtes
Authorization: Bearer $HIAPI_API_KEY transporte vos identifiants ; le shell développe la variable d'environnement exportée précédemment, de sorte que la clé n'apparaît pas en clair dans l'historique des commandes. Content-Type: application/json indique à l'API d'interpréter le corps de la requête comme du JSON. Envoyer un corps JSON en omettant cet en-tête est une cause fréquente d'erreurs difficiles à comprendre.
Le payload
model identifie fibo-2.0/image-to-image. prompt est votre instruction — décrivez l'édition, et non l'image de sortie entière, puisque l'image d'entrée porte déjà la structure. image est la forme d'image d'entrée acceptée par l'interface ; si vous l'intégrez directement, il s'agit de l'encodage base64 du contenu du fichier. n contrôle le nombre de sorties demandées ; le laisser par défaut est le point de départ le plus sûr.
Si l'image est volumineuse, l'intégrer directement dans une commande shell devient malcommode. Encodez-la d'abord dans un fichier puis référencez-le, ou passez directement à la méthode Python de la section suivante — y lire un fichier et l'encoder ne prend qu'une ligne.
Lire la réponse
Ne partez pas du principe que la réponse contient les octets d'une image terminée. Lancez l'appel curl et inspectez le JSON : ce que vous cherchez, c'est un identifiant de tâche ou un champ de statut, pour déterminer si la tâche est terminée ou toujours en cours. Capturez la structure avant d'écrire le moindre code d'analyse, car la forme de la réponse détermine la manière dont vous allez interroger le statut.
Porter la requête en Python
Python rend la requête plus facile à maintenir et permet de l'encapsuler dans une fonction réutilisable dans toute la base de code. Voici un client léger implémentant la même requête :
import base64
import os
import time
import requests
BASE_URL = "https://api.hiapi.ai/v1"
API_KEY = os.environ["HIAPI_API_KEY"]
def encode_image(path: str) -> str:
with open(path, "rb") as f:
return base64.b64encode(f.read()).decode("utf-8")
def submit_image_edit(image_path: str, prompt: str) -> dict:
payload = {
"model": "fibo-2.0/image-to-image",
"prompt": prompt,
"image": encode_image(image_path),
"n": 1,
}
response = requests.post(
f"{BASE_URL}/images/generations",
headers={"Authorization": f"Bearer {API_KEY}"},
json=payload,
timeout=60,
)
response.raise_for_status()
return response.json()
Pourquoi cette structure
Séparer encode_image de submit_image_edit rend le traitement des fichiers et celui du HTTP indépendants, et donc plus faciles à tester séparément. Lire la clé depuis l'environnement à l'import fait échouer immédiatement en cas d'absence, plutôt que de produire un 401 plusieurs couches plus loin. Définir explicitement un timeout évite qu'une connexion bloquée suspende indéfiniment un processus de travail.
Traiter le corps de la réponse
raise_for_status() transforme les échecs de la couche HTTP en exceptions capturables avec journalisation du corps de réponse — bien plus utile que d'analyser silencieusement un objet d'erreur comme s'il s'agissait d'un succès. Une fois le JSON analysé obtenu, consignez l'identifiant de tâche qu'il contient et, pendant le développement, consignez la réponse complète pour voir précisément quels champs existent. N'écrivez pas d'analyseur fondé sur des suppositions ; fondez-le sur la réponse que vous avez réellement observée.
Rester réutilisable
Deux petites améliorations rapportent vite : placer l'URL de base et le nom du modèle dans des constantes pour que les autres appels de modèle partagent ce client ; et faire retourner à la fonction de soumission une structure typée (petite dataclass ou dict à clés connues), afin que le code d'interrogation repose sur un contrat stable.
Gérer le cycle de vie asynchrone et le polling
Une tâche d'image ne se termine pas instantanément. L'intégration doit traiter la soumission et l'achèvement comme deux événements distincts.
Étape 1 : soumettre et persister
Après avoir soumis la tâche, stockez l'identifiant de tâche dans un emplacement persistant — ligne de base de données, message de file d'attente, ou au minimum une ligne de journal. Si le processus plante entre la soumission et l'achèvement, une tâche non consignée est un travail perdu. Liez l'identifiant à l'entité de votre système propriétaire du résultat, afin de pouvoir réconcilier plus tard.
Étape 2 : interroger avec backoff
Interrogez l'interface d'état de la tâche à intervalles raisonnables. Une boucle serrée martelant l'interface d'état gaspille des ressources et constitue l'erreur asynchrone la plus courante :
def wait_for_job(job_id: str, interval: float = 2.0, max_wait: float = 180.0) -> dict:
deadline = time.monotonic() + max_wait
while time.monotonic() < deadline:
response = requests.get(
f"{BASE_URL}/jobs/{job_id}",
headers={"Authorization": f"Bearer {API_KEY}"},
timeout=30,
)
response.raise_for_status()
job = response.json()
if job.get("status") in {"succeeded", "failed"}:
return job
time.sleep(interval)
interval = min(interval * 1.5, 10.0)
raise TimeoutError(f"la tâche {job_id} ne s'est pas terminée en {max_wait}s")
Commencer par un intervalle court puis l'augmenter préserve la réactivité des premières vérifications tout en évitant les requêtes à haute fréquence sur la durée. Une échéance ferme empêche d'attendre indéfiniment une tâche qui ne se terminera jamais.
Étape 3 : traiter l'échec comme un résultat normal
Une tâche terminée n'est pas nécessairement une tâche réussie. Vérifiez le statut avant de lire la sortie et gérez l'échec par une branche explicite : consignez les détails de l'erreur renvoyés par la tâche, signalez à l'appelant qu'une nouvelle tentative est possible, et décidez si le nouvel essai doit réutiliser la même entrée ou en générer une nouvelle. Une tâche dont le délai a expiré côté client peut encore tourner côté serveur : ne la soumettez pas à nouveau aveuglément sans vérification.
Étape 4 : récupérer et stocker le résultat
Une fois la tâche déclarée réussie, lisez la référence de sortie qu'elle fournit et téléchargez-la sans tarder. Pour conserver le résultat à long terme, copiez-le dans votre propre stockage plutôt que de compter sur la validité permanente de la référence.
Erreurs courantes et comment les corriger
La plupart des échecs se rangent dans quelques catégories prévisibles. Parcourez cette liste dans l'ordre.
Échec d'authentification
Un 401 ou 403 signifie presque toujours un en-tête erroné ou une clé absente. Vérifiez que l'en-tête est exactement Authorization: Bearer <key>, avec un espace après Bearer ; et confirmez que la variable d'environnement est bien définie dans le processus qui émet la requête — pas seulement dans votre shell interactif. Un espace final ou des guillemets superflus lors du copier-coller de la clé représentent une part considérable de ces problèmes.
Format de payload incorrect
Un 400 ou 422 signifie généralement que l'API ne peut pas interpréter le corps de la requête. Vérifiez trois choses dans l'ordre : la présence de Content-Type: application/json, la validité du JSON (une virgule finale le casse), et l'existence des champs requis sous les bons noms. Si vous envoyez des données d'image en base64, vérifiez qu'il s'agit de base64 valide et que le format de fichier sous-jacent est pris en charge — une chaîne tronquée ou doublement encodée produit des erreurs de validation déroutantes.
Erreurs de polling
Si une tâche semble ne jamais se terminer, vérifiez que vous interrogez avec l'identifiant réellement renvoyé dans la réponse de soumission, et que vous lisez le bon champ de statut. Une boucle serrée qui ignore l'état failed ressemblera à un blocage. Ajoutez un délai maximal strict et consignez les changements de statut observés ; ce journal révèle souvent le problème immédiatement.
Pièges d'analyse de la réponse
Si le code lève une exception lors de la lecture du résultat, ne devinez pas la forme de la réponse. Consignez d'abord le corps brut. Les problèmes courants incluent : prendre une référence pour des octets, supposer qu'un champ présent uniquement en cas de succès existe toujours, ou analyser une réponse de succès avec un analyseur prévu pour les échecs. Construisez la logique d'extraction à partir des réponses que vous avez réellement vues.
Réflexe de tri rapide
En cas de problème, isolez d'abord la couche : exécutez la commande curl avec le même payload. Si curl réussit et Python échoue, le problème est côté client ; si les deux échouent, il est dans la requête. Ce test simple fait gagner plus de temps que n'importe quelle autre habitude de débogage.
Avec un appel fonctionnel et une boucle de polling robuste, fibo-2.0/image-to-image devient une étape d'édition fiable — commencez par la page du modèle sur HiAPI, puis adaptez les requêtes ci-dessus à vos propres images.
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