Blog

Tutoriel

Comment appeler fibo-edit-1.5 image-to-image via l'API HiAPI : guide curl et Python

Explication pratique des requêtes exécutables pour l'édition d'image pilotée par instruction

Nov 17, 2026
Image de couverture : sur un fond presque noir, une bande de points vert menthe allant du clairsemé au dense, le bord droit agrémenté d'un groupe de points bleu-vert foncé.
Sur cette page

Ce que permet le point de terminaison fibo-edit-1.5 image-to-image

fibo-edit-1.5/image-to-image est un point de terminaison d'édition d'image piloté par instruction. Il ne décrit pas une scène à partir de zéro : il reçoit une image de référence et une instruction en langage naturel, puis renvoie une nouvelle image dans laquelle l'édition est appliquée tandis que le reste de la composition demeure inchangé.

Cette position influence directement la manière de concevoir votre requête. L'image de référence porte le contexte visuel — sujet, cadrage, éclairage, style — tandis que l'instruction porte la modification. Une bonne instruction précise clairement ce qui doit changer et reste silencieuse sur ce qui doit être conservé. « Remplace le ciel par un coucher de soleil nuageux, garde le bâtiment et le premier plan inchangés » transmet bien plus d'informations que « rends-le plus beau ».

Un appel réussi produit une ressource d'image éditée. Selon la manière dont le point de terminaison est appelé, la réponse renvoie la sortie générée sous une forme que vous pouvez enregistrer ou récupérer — consultez la référence du point de terminaison pour connaître la structure exacte de la réponse et les paramètres pris en charge. Considérez cette référence comme la seule source faisant autorité pour les noms de champs, les formats d'image acceptés et les limites de taille, car ces détails peuvent évoluer indépendamment de ce document.

Les usages typiques incluent la retouche de photos produit, le remplacement d'arrière-plan, l'ajustement de style et les éditions locales où une régénération complète ferait perdre en fidélité. Si votre tâche consiste uniquement à générer à partir de texte plutôt qu'à éditer, ce point de terminaison n'est pas le bon outil ; utilisez plutôt un modèle texte-vers-image.

Une attente à établir dès le départ : l'édition est par nature itérative. Votre première instruction aboutit rarement parfaitement, alors structurez votre flux de travail autour d'itérations peu coûteuses — ne modifiez qu'une variable à la fois, gardez l'image de référence inchangée et comparez les sorties avant de passer à l'étape suivante.

Ce qui compose une requête exploitable

Avant d'écrire le moindre code, identifiez clairement les entrées nécessaires à une requête. Chaque appel à fibo-edit-1.5/image-to-image combine quatre catégories d'informations.

Authentification

Toutes les requêtes passent par l'interface unifiée HiAPI et transportent votre clé d'API dans l'en-tête Authorization. Placez la clé dans une variable d'environnement plutôt que dans le code source, et ne la validez jamais.

Image de référence

Vous devez fournir l'image source sur laquelle s'applique l'édition. Deux formes sont courantes : une URL publique que le service peut récupérer, ou des données encodées en base64 intégrées dans le corps JSON de la requête. L'URL facilite les itérations ; le base64 évite de dépendre d'un hébergement externe. Consultez la référence du point de terminaison pour savoir quelles formes sont acceptées ainsi que les éventuelles contraintes de taille ou de résolution.

Instruction d'édition

Il s'agit d'une chaîne en langage courant décrivant la modification. Rédigez-la à l'impératif, désignez la zone ou l'élément à modifier et précisez ce qui doit être préservé. Évitez d'empiler plusieurs éditions sans rapport dans une même instruction — séparez-les en plusieurs appels, afin de pouvoir déterminer laquelle a produit un mauvais résultat.

Contrôle de la sortie

Des réglages optionnels, comme les dimensions, le format de sortie ou le nombre d'images candidates. Conservez les valeurs par défaut au premier appel, puis ajustez délibérément par la suite. Chaque paramètre que vous définissez est une variable supplémentaire à écarter en cas de problème.

Ainsi, un corps de requête minimal comporte deux champs substantiels — l'image et l'instruction — encapsulés dans un objet JSON, éventuellement accompagnés de vos préférences de sortie. Si vous pouvez répondre à « quelle image, quelle modification, sous quel format je veux le résultat », vous disposez de tout le nécessaire pour écrire cet appel.

Lancer l'appel avec curl

Commencez par curl : il isole la couche HTTP, de sorte qu'en cas de problème, vous savez qu'il provient de la requête et non du code applicatif.

Exportez d'abord votre clé :

 export HIAPI_API_KEY="your-api-key"

Envoyez ensuite le corps JSON contenant l'URL de l'image de référence et l'instruction :

curl -sS https://api.hiapi.ai/v1/fibo-edit-1.5/image-to-image \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "https://example.com/input.jpg",
    "prompt": "Remplace le ciel terne par un doux dégradé de coucher de soleil ; garde le bâtiment et le premier plan inchangés."
  }'

Quelques conseils pratiques :

  • Vérifiez l'URL de base et le chemin dans la référence du point de terminaison, ne les recopiez pas de mémoire.
  • Utilisez -sS, pour que curl reste silencieux en cas de succès tout en affichant les erreurs de transport.
  • Si vous ne voulez pas dépendre d'un hébergement externe, encodez le fichier en base64 et remplacez la valeur de image par la chaîne encodée, en respectant le nom de champ indiqué dans la référence.
  • Pendant l'exploration, faites passer la sortie par jq . pour rendre la réponse plus lisible.

Pour confirmer la réponse, recherchez la charge utile ou l'URL de l'image renvoyée et ouvrez-la. Si le corps de la réponse contient un objet d'erreur, notez ses champs type et message — ils vous indiqueront si le problème vient de l'image, de l'instruction ou de la structure de la requête. Enregistrez une réponse brute réussie dans un fichier ; elle servira de fixture de test lorsque vous écrirez le client Python, et de preuve en cas de changement de comportement ultérieur.

Effectuer la même requête avec Python

La version Python doit être strictement identique à l'appel curl — même chemin, mêmes en-têtes, même corps — afin que toute différence soit un bug de votre code et non une différence dans ce que vous demandez.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
URL = "https://api.hiapi.ai/v1/fibo-edit-1.5/image-to-image"

payload = {
    "image": "https://example.com/input.jpg",
    "prompt": (
        "Remplace le ciel terne par un doux dégradé de coucher de soleil ; "
        "garde le bâtiment et le premier plan inchangés."
    ),
}

response = requests.post(
    URL,
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=120,
)
response.raise_for_status()
result = response.json()
print(result)

Envoyer un fichier local

Si vous éditez un fichier présent sur le disque, encodez-le et envoyez la chaîne plutôt qu'une URL :

import base64

with open("input.jpg", "rb") as f:
    encoded = base64.b64encode(f.read()).decode("utf-8")

payload = {
    "image": encoded,
    "prompt": "Change l'arrière-plan en un gris neutre propre ; garde le produit net.",
}

Avant de vous appuyer sur cette méthode, vérifiez dans la référence du point de terminaison le nom exact du champ et l'encodage attendu.

Stocker la sortie

Écrivez l'image renvoyée sur le disque, afin de pouvoir comparer les itérations côte à côte et d'enregistrer quelle instruction a produit quel résultat. Une petite fonction utilitaire qui enregistre la sortie sous un nom dérivé d'un hachage de l'instruction rendra les comparaisons ultérieures triviales.

Définissez toujours un timeout explicite. L'édition d'image prend plus de temps qu'un simple appel texte, et une requête sans limite de délai laissera un processus de travail suspendu indéfiniment en cas de blocage réseau.

Gérer les erreurs et réessayer en toute sécurité

Les échecs se répartissent en quelques grandes catégories, chacune nécessitant une réponse différente.

Erreurs client

La requête elle-même est erronée : JSON mal formé, champ image manquant, format d'image non pris en charge, instruction que le modèle ne peut pas exécuter, ou problème d'authentification. Réessayer ces erreurs telles quelles ne ferait que gaspiller du temps et du quota — elles échoueront exactement de la même manière. Corrigez plutôt la requête. Face à ce type d'erreur, enregistrez le corps complet de la requête (partie image tronquée) et le message d'erreur, puis corrigez l'entrée.

Limites de débit

Vous envoyez des requêtes plus vite que le quota autorisé. La bonne réaction est de reculer et de réessayer, plutôt que de marteler le point de terminaison. Suivez les indications de nouvelle tentative fournies dans la réponse ; à défaut, utilisez un backoff exponentiel.

Erreurs serveur et transitoires

Les délais d'attente, les réinitialisations de connexion et les défaillances en amont méritent une nouvelle tentative. C'est là que la logique de nouvelle tentative idempotente entre en jeu.

Stratégie de nouvelle tentative pratique

  • Ne réessayez qu'en cas de délai d'attente, d'erreur de connexion, de limite de débit ou de réponse serveur.
  • Utilisez un backoff exponentiel plafonné — par exemple, commencez par un court délai, doublez-le à chaque tentative et arrêtez après un petit nombre fixe de tentatives.
  • Ajoutez une gigue au délai, pour que les processus parallèles ne réessaient pas tous au même instant.
  • Ne réessayez jamais une requête rejetée pour un problème de schéma, de format ou d'instruction.
  • Journalisez chaque tentative avec son numéro et son résultat, afin de voir si les échecs sont concentrés.
import random, time, requests

def edit_with_retry(payload, attempts=4):
    delay = 1.0
    for i in range(attempts):
        try:
            r = requests.post(URL, headers=HEADERS, json=payload, timeout=120)
        except (requests.Timeout, requests.ConnectionError):
            pass
        else:
            if r.status_code < 400:
                return r.json()
            if r.status_code not in (429, 500, 502, 503, 504):
                r.raise_for_status()
        time.sleep(delay + random.uniform(0, 0.5))
        delay = min(delay * 2, 30)
    raise RuntimeError("l'édition a encore échoué après les nouvelles tentatives")

Considérez ceci comme une base : alignez les codes de statut réessayables sur ce que le point de terminaison renvoie réellement, et centralisez la stratégie à un seul endroit pour que tous les appelants la partagent.

Vérifications avant la mise en production

Avant de brancher le point de terminaison en production, parcourez une courte liste de vérifications.

Valider deux fois le chemin nominal

Exécutez à nouveau votre appel curl enregistré et votre client Python sur les mêmes entrées, en confirmant qu'ils produisent des résultats équivalents. S'ils divergent, c'est que vos corps de requête ne sont en réalité pas identiques.

Calibrer les instructions sur des entrées réelles

Testez vos instructions sur des images représentatives, pas seulement sur un échantillon unique. La qualité de l'édition dépend fortement de la précision de l'instruction et de la capacité de l'image de référence à soutenir cette modification. Conservez un petit ensemble de paires prompt-sortie comme suite de tests de régression ; lorsque vous ajustez la formulation, vous verrez ce qui s'améliore et ce qui régresse.

Vérifier les limites et les formats

Confirmez dans la référence du point de terminaison les formats d'image acceptés, les dimensions maximales et toute limite de taille de requête. Validez localement avant l'envoi — rejeter une mauvaise image côté client est plus rapide et moins coûteux qu'un aller-retour.

Vérifier les clés et les journaux

Assurez-vous que la clé d'API provient d'une variable d'environnement, que les journaux de requête tronquent la charge utile de l'image et qu'aucune clé n'apparaît dans les rapports d'erreur.

Confirmer le comportement en cas d'échec

Provoquez de force un délai d'attente et un corps de requête mal formé dans un environnement de préproduction, vérifiez que votre stratégie de nouvelle tentative se comporte correctement et que les échecs permanents sont remontés à l'appelant au lieu de disparaître silencieusement.

Une fois tout cela validé, l'intégration deviendra banale, et c'est tant mieux. Récupérez la liste faisant autorité des paramètres dans la référence du point de terminaison fibo-edit-1.5 image-to-image, puis construisez à partir d'un appel curl fonctionnel.

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