Tutoriel
Comment appeler flux-1-fill-pro via l'API HiAPI : curl, Python et interrogation asynchrone
Sur cette page
Rôle de flux-1-fill-pro et cas d'usage
flux-1-fill-pro est un modèle d'édition d'image de type remplissage. Vous lui fournissez une image source et un masque marquant la zone à régénérer, et il produit une nouvelle image dans laquelle cette zone a été remplacée. Les zones situées hors du masque sont censées rester inchangées : c'est précisément ce qui le distingue d'un modèle de génération texte-image pur ou d'un modèle de stylisation de l'image entière.
Utilisez-le lorsque l'édition est locale et que le contexte environnant compte :
- Suppression d'objet — encerclez l'élément indésirable avec le masque et laissez le modèle reconstruire ce qui devrait se trouver derrière.
- Remplacement d'objet — délimitez une zone avec le masque, décrivez le nouveau contenu dans le prompt tout en conservant le reste de la scène.
- Retouche locale — corrigez des textures, des reflets ou de petits défauts sans régénérer toute l'image.
- Insertion dans un pipeline — retouchez par programmation des photos produit, des vignettes ou des assets générés, lorsqu'une seule zone nécessite un second passage.
Ce n'est pas l'outil adapté lorsque vous souhaitez obtenir une composition entièrement nouvelle à partir d'un prompt, ou lorsque votre zone masquée est si grande que le modèle génère en réalité une image à partir de zéro — dans ce cas, le point de terminaison de génération standard sera plus prévisible.
Le reste de ce guide explique comment intégrer flux-1-fill-pro dans du code via l'API HiAPI : structure de la requête, appel curl, équivalent Python et gestion des tâches asynchrones que la plupart des premières intégrations ratent.
Préparation et configuration de l'authentification
Avant d'envoyer votre première requête, vérifiez trois choses.
Clé d'API
Créez une clé dans votre compte HiAPI et gardez-la hors du contrôle de version. Les exemples ci-dessous la lisent depuis une variable d'environnement, afin que les extraits soient sûrs à copier :
export HIAPI_API_KEY="your_key_here"
En Python, chargez-la de la même manière via os.environ. Si vous exécutez en CI, injectez-la comme secret plutôt que de committer un fichier .env.
Identifiant du modèle
Chaque requête désigne le modèle par son nom. Dans ce guide, l'identifiant est flux-1-fill-pro. Conservez-le comme constante dans le code plutôt que de disperser des littéraux de chaîne — ainsi, changer de modèle ne nécessitera qu'une seule ligne de modification.
URL de base
Tous les appels partent de l'URL de base de l'API HiAPI documentée dans la référence de la plateforme. Placez-la dans la configuration avec la clé, afin que les environnements de préproduction et de production puissent différer sans modifier le code.
Une remarque structurelle avant de commencer : les requêtes de remplissage transportent des données d'image. Envoyez les images encodées en base64 sous forme de JSON, plutôt que d'essayer de forcer un upload multipart ; et gardez un délai d'expiration généreux côté client — l'encodage de grandes images ajoute de la latence avant même que la requête ne quitte votre processus. Consultez la documentation de la plateforme pour connaître les limites actuelles de taille de payload ; si votre image source dépasse la limite documentée, réduisez-la avant l'encodage plutôt que de laisser la requête échouer en périphérie.
Structure d'une requête d'inpainting
Quel que soit le langage utilisé, chaque appel à flux-1-fill-pro possède la même composition logique.
Image source
L'image à éditer, encodée sous forme de chaîne. Elle définit le canevas : ses dimensions déterminent l'espace de coordonnées dans lequel le masque s'applique, et son contenu fournit au modèle le contexte qui rend le remplissage crédible.
Masque
Le masque indique quelles zones seront régénérées. C'est la source de confusion la plus fréquente : vérifiez donc explicitement la convention appliquée à votre payload : la zone marquée par le masque est celle que le modèle est autorisé à modifier. Construisez le masque comme une image distincte, où la zone à remplir se distingue visuellement de la zone à conserver. Inverser le masque est le bug classique — vous obtenez un résultat où le modèle a édité tout sauf la zone souhaitée.
Le masque doit avoir exactement les mêmes dimensions que l'image source. Un masque dessiné à une autre résolution sera soit rejeté, soit silencieusement décalé, et dans les deux cas vous aurez perdu un aller-retour.
Prompt
La description textuelle de ce qui doit apparaître à l'intérieur du masque. Restez précis et local : décrivez le contenu et sa relation avec l'environnement en matière d'éclairage ou de texture, et non la scène entière. « un banc en bois prolongeant la moulure de la vitrine, lumière douce d'après-midi à gauche » donne plus de prise au modèle que « un plus joli arrière-plan ».
Contrôles optionnels
Selon le jeu de paramètres documenté, vous pouvez aussi transmettre par exemple une seed pour la reproductibilité, ou un paramètre de type force contrôlant dans quelle mesure le remplissage peut s'écarter des pixels d'origine. Traitez tout paramètre absent de la référence actuelle comme non pris en charge plutôt que de deviner son nom.
Ces quatre éléments — modèle, prompt, image source, masque — sont transmis dans un même corps JSON. Les deux sections suivantes envoient précisément ce corps.
Une requête curl fonctionnelle
Commencez par curl, afin de voir l'enveloppe brute avant que toute bibliothèque cliente ne la masque.
curl -sS -X POST "$HIAPI_BASE_URL/v1/images/edits" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @request.json
où request.json se présente comme suit :
{
"model": "flux-1-fill-pro",
"prompt": "un banc en bois prolongeant la moulure de la vitrine, lumière douce d'après-midi à gauche",
"image": "<base64-encoded source image>",
"mask": "<base64-encoded mask image>"
}
Deux astuces pratiques pour construire ce fichier. Premièrement, générez les payloads base64 par commande plutôt que de les coller à la main :
base64 -w 0 source.png > source.b64
base64 -w 0 mask.png > mask.b64
Puis assemblez request.json à l'aide d'une petite étape jq ou Python qui les intègre. Éditer à la main des blocs base64 de plusieurs mégaoctets dans du JSON est précisément la source de payloads tronqués et d'erreurs 400 déroutantes.
Interpréter la réponse
L'enveloppe de réponse vous indique la marche à suivre. Une tâche terminée renvoie l'image éditée — généralement sous forme d'URL ou de champ base64, selon le format spécifié par la référence actuelle. Une tâche mise en file renvoie un identifiant et un statut, que vous interrogerez ensuite (voir ci-dessous). Ne supposez pas que la première réponse contient toujours les pixels ; écrivez votre parseur dès le premier jour pour gérer les deux formes, sinon vous devrez le réécrire dès la première fois qu'une tâche sera mise en file sous charge.
Vérifiez le code de statut HTTP avant de parser le corps de la réponse. Un 4xx signifie que la requête elle-même est erronée, et réessayer n'y changera rien ; corrigez plutôt le payload.
Le même appel en Python
La version Python est la même requête, mais plus confortable à utiliser. Pas besoin de SDK — requests suffit pour appeler le point de terminaison HiAPI.
import base64
import json
import os
import time
import requests
BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = "flux-1-fill-pro"
def b64(path: str) -> str:
with open(path, "rb") as f:
return base64.b64encode(f.read()).decode("ascii")
def create_fill(source_path: str, mask_path: str, prompt: str) -> dict:
payload = {
"model": MODEL,
"prompt": prompt,
"image": b64(source_path),
"mask": b64(mask_path),
}
resp = requests.post(
f"{BASE_URL}/v1/images/edits",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
data=json.dumps(payload),
timeout=120,
)
if resp.status_code >= 400:
raise RuntimeError(f"HiAPI error {resp.status_code}: {resp.text}")
return resp.json()
Le timeout est intentionnel. L'encodage et l'upload de grandes images prennent plus de temps qu'un appel JSON typique, et une requête sans limite est précisément ce qui fait suspendre silencieusement un script dans des tâches par lots. Lever une exception sur un 4xx avec le corps de la réponse transforme un échec mystérieux en échec lisible.
Placez l'identifiant du modèle et le point de terminaison dans la configuration au niveau du module, afin qu'une montée de version ne nécessite qu'une seule modification. Si vous traitez beaucoup d'images, réutilisez une requests.Session pour que les connexions soient mises en pool plutôt que recréées à chaque appel.
Le dictionnaire parsé est soit un résultat terminé, soit un handle de tâche — la section suivante traite ce dernier cas.
Gérer les tâches asynchrones et l'interrogation
Les requêtes de remplissage peuvent être lentes, l'API peut donc renvoyer un handle de tâche plutôt que l'image finale. Le bon modèle est une boucle d'interrogation bornée, et non un sleep fixe suivi d'une prière.
La boucle
def wait_for_result(job: dict, *, interval=2.0, timeout=180.0) -> dict:
deadline = time.monotonic() + timeout
current = job
while time.monotonic() < deadline:
status = current.get("status")
if status in {"succeeded", "completed"}:
return current
if status in {"failed", "canceled", "cancelled"}:
raise RuntimeError(f"Job ended as {status}: {current}")
time.sleep(interval)
interval = min(interval * 1.5, 15.0) # backoff modéré
current = fetch_job(current["id"])
raise TimeoutError(f"Job {job.get('id')} exceeded {timeout}s")
fetch_job suit le même schéma de requête que ci-dessus, en utilisant l'id de la tâche et vos en-têtes d'authentification pour appeler le point de terminaison de statut documenté.
Pourquoi un backoff plutôt qu'un intervalle fixe
Interroger une file en boucle serrée martèle l'API sans aucun bénéfice. Commencer par un intervalle court et le multiplier progressivement jusqu'à un plafond maintient une réactivité rapide pour les tâches qui se terminent tôt, sans gaspiller des milliers d'interrogations sur des tâches lentes. Plafonnez l'intervalle pour rester capable de détecter une fin en quelques secondes.
Pourquoi un timeout n'est pas un échec
Un timeout signifie que vous avez arrêté d'attendre, pas que la tâche a échoué. Conservez l'id de la tâche lorsque vous levez l'exception, afin que l'appelant puisse reprendre l'interrogation plus tard sans resoumettre et payer deux fois le même travail. Traitez les timeouts, les échecs de tâche et les erreurs HTTP comme trois exceptions distinctes dans votre pipeline — les comprimer en une erreur générique rend le diagnostic des incidents de production bien plus difficile.
Déboguer les pannes courantes
La plupart des réponses d'erreur se répartissent en quelques catégories. Vérifiez-les dans l'ordre.
401 / 403 — authentification
Première vérification : l'en-tête est-il exactement Authorization: Bearer <key>, sans guillemets ni espaces superflus provenant d'une variable shell jamais exportée ? Un $HIAPI_API_KEY vide produit un jeton Bearer réduit au seul mot Bearer, qui échoue de la même manière qu'une mauvaise clé.
400 — payload mal formé
Première vérification : le corps de la requête est-il toujours un JSON valide après concaténation de la chaîne base64 ? Exportez request.json et passez-le dans python -m json.tool. Un préfixe data:image/png;base64, sur les champs d'image est une cause fréquente — retirez-les, sauf si la référence l'exige explicitement.
Incompatibilité masque/image
Première vérification : les dimensions en pixels du masque et de l'image source sont-elles exactement identiques ? Vérifiez ensuite la polarité — confirmez que la zone blanche correspond à la zone que vous voulez que le modèle régénère. Un résultat qui semble inversé par rapport à votre demande provient presque toujours d'un masque inversé, pas du prompt.
Débordement du prompt
Si des zones non masquées changent, ou si le remplissage semble global, votre masque est peut-être trop grand ou le prompt trop englobant. Resserrez les deux : limitez le masque à la zone d'édition réelle et ne décrivez que le contenu du masque.
Timeout de tâche
Première vérification : la taille du payload. Une image source trop grande est la cause la plus fréquente d'une tâche qui ne se termine jamais. Réduisez-la, réessayez une fois, et si le timeout persiste, comparez avec les limites de référence à l'aide d'une petite image de test avant de supposer un problème de service.
Champ de résultat vide ou manquant
Première vérification : avez-vous géré la forme de la réponse de mise en file ? Un parseur qui ne lit que la forme terminée ne verra rien au premier appel. Journalisez l'enveloppe de réponse complète pendant le développement, afin de voir la forme avant d'écrire du code défensif.
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