Blog

Tutoriel

Utiliser flux-2/image-to-image via l'API HiAPI : tutoriel curl et Python

Nov 12, 2026
Image de couverture : sur un fond vert pin profond, plusieurs grands prismes sont découpés en biais en aplats de couleur réguliers, et les facettes géométriques vert cyan et vert brume forment un ensemble simple et ordonné.
Sur cette page

À quoi sert flux-2/image-to-image et dans quels cas l'utiliser

flux-2/image-to-image est un point de terminaison d'édition, et non un simple générateur texte-vers-image. Vous devez lui fournir deux choses : une image de référence et une instruction d'édition rédigée en langage naturel. Le modèle lit l'image de référence comme un contexte visuel — sujet, composition, style, éclairage — et produit une nouvelle image qui suit vos instructions tout en restant ancrée dans cette référence.

Cette distinction est importante lors de la conception d'un pipeline. Avec le texte-vers-image, vous décrivez tout depuis zéro et espérez que le modèle s'approche de votre intention. Avec l'image-vers-image, vous disposez déjà d'un support visuel et vous voulez une transformation contrôlée : restyler une photo produit, remplacer l'arrière-plan, ajuster l'ambiance d'une scène, ou itérer sur un design en gardant la composition sous-jacente stable.

Cas d'usage adaptés

  • Variantes d'assets. Générer plusieurs traitements stylisés à partir d'une image de référence validée.
  • Édition guidée. Appliquer des modifications ciblées (« réchauffer la lumière », « remplacer l'arrière-plan par un mur de studio uni ») sans régénérer toute la scène.
  • Cohérence sur un lot de résultats. Réutiliser la même image de référence pour que toute une série de sorties partage le même ancrage visuel.
  • Outils d'édition humain-dans-la-boucle. Permettre à un utilisateur de téléverser une image, de décrire une modification, et de récupérer le résultat dans votre propre interface.

Cas d'usage inadaptés

  • La retouche ou le compositing au pixel près. C'est un modèle génératif, pas un éditeur d'image matricielle.
  • Les situations sans aucune image de référence — le texte-vers-image est alors un meilleur point de départ.
  • Tout workflow où l'on attend que l'instruction porte seule l'intégralité des détails ; l'image de référence joue un rôle réel, et une mauvaise référence ne produira que de mauvais résultats.

Considérez ce point de terminaison comme image de référence + instruction -> image éditée. Tout le contenu de ce tutoriel repose sur cette forme : comment l'envoyer, comment lire ce qui revient, et comment le maintenir en fonctionnement quand le réseau ne coopère pas.

Prérequis et configuration de l'authentification

Avant le premier appel, préparez trois choses.

1. Un compte HiAPI

Inscrivez-vous et ouvrez la console. Toutes les requêtes de ce tutoriel passent par l'API unifiée HiAPI, vous n'avez donc pas besoin de vous inscrire séparément chez un fournisseur ni d'installer un SDK par fournisseur.

2. Une clé d'API

Créez une clé d'API dans la console. Traitez-la comme un mot de passe : ne la validez pas dans un dépôt de code, ne la collez pas dans du code client et ne la consignez pas dans les journaux. La bonne pratique consiste à la charger depuis une variable d'environnement au moment de l'exécution :

export HIAPI_API_KEY="your-api-key-here"

Référencez ensuite HIAPI_API_KEY là où la clé est nécessaire. Si vous déployez sur un conteneur ou une plateforme serverless, définissez-la comme secret dans cet environnement plutôt que de l'intégrer à l'image.

3. Une image de référence accessible

Le point de terminaison exige une image de référence, il faut donc décider à l'avance comment la fournir. Deux approches courantes :

  • Une URL que l'API peut récupérer, par exemple un lien signé pointant vers votre propre stockage objet.
  • Des octets encodés en Base64, envoyés en ligne dans le corps de la requête, ce qui évite d'exposer une URL interne mais augmente la taille de la charge utile.

Choisissez d'abord une petite image de test — quelques centaines de Ko suffisent pour valider l'intégration. Les téléversements de gros fichiers ralentissent chaque nouvelle tentative et compliquent le débogage.

Point de contrôle

Vous devriez maintenant avoir une clé stockée dans une variable d'environnement et une image de test accessible depuis votre machine. Efforcez-vous de garder la clé hors de l'historique du shell (un fichier .env chargé par vos outils est généralement plus propre qu'un export en ligne de commande).

Il y a aussi une habitude à prendre dès maintenant : journalisez l'identifiant de requête et la durée dès le premier jour. Quand la production pose problème, la différence entre une requête traçable et une requête non traçable est énorme.

Construire la requête : image de référence et instruction d'édition

Chaque appel image-vers-image se construit autour de deux entrées. Faites-les bien, et le reste n'est que plomberie.

Entrée un : l'image de référence

L'image de référence est l'ancrage. Elle indique au modèle ce que la scène contient et à quoi elle ressemble avant toute édition. Conseils pratiques :

  • Alignez le rapport d'aspect sur la sortie souhaitée. Si la référence est un format paysage large alors que vous voulez une sortie carrée, attendez-vous à un recadrage ou à une déformation selon la configuration de l'appel.
  • Partez d'une image nette et bien éclairée. Une référence trouble produira des éditions troubles.
  • Privilégiez un seul sujet clair. Un collage encombré donne au modèle trop d'ancrages concurrents.

Entrée deux : l'instruction d'édition

L'instruction est la description en langage naturel de la modification souhaitée. C'est là que se joue l'essentiel des écarts de qualité. Traitez-la comme un prompt accompagné d'une image de référence.

  • Énoncez la modification, pas toute la scène. « Remplacer l'arrière-plan par un mur de studio blanc uni » vaut mieux que « un produit sur fond blanc » — cette dernière formulation pousse le modèle à tout redessiner.
  • Précisez ce qui doit être préservé. Des formulations comme « garder la pose et la composition du sujet inchangées » réduisent nettement la dérive.
  • Détaillez le style et la lumière. « Lumière douce de ciel couvert, couleurs désaturées » donne plus d'informations exploitables au modèle que « rends-le plus beau ».
  • Évitez les contradictions. Si la référence est une scène extérieure de jour et que vous demandez un intérieur nocturne, attendez-vous à un arbitrage du modèle qui pourrait ne pas vous plaire.

Le corps de la requête

La requête envoyée à flux-2/image-to-image contient l'identifiant du modèle, l'image de référence et l'instruction. Un modèle mental utile :

{
  "model": "flux-2/image-to-image",
  "input": {
    "image": "<URL ou image de référence base64>",
    "prompt": "<instruction d'édition>"
  }
}

Si votre référence est en base64, construisez une data URI conforme au schéma de la requête, ou transmettez l'encodage brut avec le type MIME. S'il s'agit d'une URL, assurez-vous que le lien est accessible publiquement pendant l'appel — un lien signé qui expire en cours de requête produit des échecs difficiles à comprendre.

Itérez d'abord, intégrez ensuite

Avant de brancher quoi que ce soit dans du code, écrivez deux ou trois instructions pour la même image de référence et comparez les sorties. Le modèle est prévisible quand les instructions sont précises et instable quand elles sont vagues ; apprendre cela maintenant coûte bien moins cher qu'en production.

Une requête curl fonctionnelle

Le moyen le plus rapide de valider la clé, l'image de référence et l'instruction est un appel curl. L'exemple ci-dessous suppose que votre clé est dans HIAPI_API_KEY et que l'image de référence est accessible par URL.

curl -sS -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2/image-to-image",
    "input": {
      "image": "https://your-bucket.example.com/reference.jpg",
      "prompt": "Remplacer l'arrière-plan par un mur de studio blanc uni. Garder la pose, la composition et l'éclairage sur le sujet inchangés."
    }
  }'

Quelques points à noter :

  • La clé passe par l'en-tête Authorization en tant que jeton bearer. Ne la mettez jamais dans l'URL.
  • Content-Type vaut JSON. Oublier de le définir est une cause fréquente de 4xx déroutants.
  • L'identifiant du modèle figure dans le corps de la requête, si bien que le même point de terminaison peut router vers d'autres modèles en changeant un seul champ.
  • L'instruction est une phrase complète, pas une liste de mots-clés. C'est intentionnel — voir la section précédente.

Lire la sortie brute

Lancez-la une fois et examinez toute la réponse avant d'écrire du code d'analyse. Au besoin, formatez-la avec un outil :

curl -sS -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json | python -m json.tool

Conserver le corps de la requête dans un fichier (request.json) est plus simple que d'éditer une chaîne entre guillemets dans le shell, et cela vous laisse un artefact persistant pour reproduire un bug plus tard.

Si vous avez besoin de base64 plutôt que d'une URL

Remplacez la valeur de image par une data URI construite à partir de votre fichier :

python - <<'PY'
import base64, json, pathlib
data = base64.b64encode(pathlib.Path("reference.jpg").read_bytes()).decode()
body = {
    "model": "flux-2/image-to-image",
    "input": {
        "image": f"data:image/jpeg;base64,{data}",
        "prompt": "Rendre la lumière plus chaude et réduire légèrement le contraste.",
    },
}
pathlib.Path("request.json").write_text(json.dumps(body))
PY

Le même appel curl fonctionne alors, puisque la charge utile est stockée dans request.json. Si l'appel réussit, vous avez tout ce qu'il faut pour passer à Python.

Le même appel en Python

La version Python est volontairement simple : construire le même dictionnaire, l'envoyer avec les mêmes en-têtes, et placer le point de terminaison et le modèle dans des constantes pour éviter toute divergence avec la version curl.

import os
import requests

API_URL = "https://api.hiapi.ai/v1/images/generations"
MODEL = "flux-2/image-to-image"


def edit_image(reference_url: str, instruction: str, timeout: float = 60.0) -> dict:
    api_key = os.environ["HIAPI_API_KEY"]  # échoue immédiatement si non définie
    payload = {
        "model": MODEL,
        "input": {
            "image": reference_url,
            "prompt": instruction,
        },
    }
    response = requests.post(
        API_URL,
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=timeout,
    )
    response.raise_for_status()
    return response.json()


if __name__ == "__main__":
    result = edit_image(
        "https://your-bucket.example.com/reference.jpg",
        "Remplacer l'arrière-plan par un mur de studio blanc uni. "
        "Garder la pose, la composition et l'éclairage sur le sujet inchangés.",
    )
    print(result)

Pourquoi cette organisation

  • os.environ["HIAPI_API_KEY"] plutôt que .get(), pour qu'une clé manquante échoue immédiatement au lieu d'envoyer une requête non authentifiée.
  • timeout est explicite. La génération d'images n'est pas instantanée ; une requête sans délai d'attente finira par bloquer un worker.
  • Appelez raise_for_status() avant l'analyse. Vous voulez une exception sur un 4xx ou 5xx, pas un KeyError déroutant plus loin.
  • Le point de terminaison et le modèle sont des constantes de module, ce qui permet à une suite de tests de pointer facilement vers un serveur factice.

Utiliser une entrée base64

Si vous transmettez des octets plutôt qu'une URL, encodez le fichier et construisez la data URI au même endroit que le reste de la charge utile :

import base64, pathlib

def as_data_uri(path: str, mime: str = "image/jpeg") -> str:
    raw = pathlib.Path(path).read_bytes()
    return f"data:{mime};base64," + base64.b64encode(raw).decode()

Appelez ensuite edit_image(as_data_uri("reference.jpg"), instruction). Séparez l'étape d'encodage de la fonction de requête, pour pouvoir tester unitairement la validation et l'assemblage du prompt sans toucher au réseau.

Analyser la réponse

L'appel renvoie un objet JSON. Extrayez maintenant l'image éditée d'une manière qui ne casse pas si la réponse gagne des champs à l'avenir.

Vérifier d'abord, supposer ensuite

En développement, exportez une réponse brute et repérez où se trouve la référence de l'image — généralement une URL ou une charge base64 imbriquée dans la structure de résultat. Écrivez ensuite des accesseurs qui vérifient sa présence au lieu de plonger directement dans des clés imbriquées.

def extract_image_url(response: dict) -> str:
    data = response.get("data") or []
    if not data:
        raise ValueError(f"Aucune donnée d'image dans la réponse : {response}")
    first = data[0]
    url = first.get("url") or first.get("b64_json")
    if not url:
        raise ValueError(f"Charge d'image non reconnue : {first}")
    return url

Deux habitudes à conserver dans ce code : échouer bruyamment en incluant la charge réelle dans le message d'erreur, et accepter l'une ou l'autre forme (URL ou base64) au lieu d'en coder une en dur. Les formats de réponse évoluent ; un lecteur tolérant survit.

Persistez immédiatement

L'URL renvoyée peut être temporaire. Si l'image compte, téléchargez-la et stockez-la dans votre propre bucket au sein de la même tâche :

def persist(url: str, dest: str) -> None:
    if url.startswith("data:"):
        header, b64 = url.split(",", 1)
        import base64, pathlib
        pathlib.Path(dest).write_bytes(base64.b64decode(b64))
        return
    with requests.get(url, stream=True, timeout=60) as r:
        r.raise_for_status()
        with open(dest, "wb") as f:
            for chunk in r.iter_content(1 << 16):
                f.write(chunk)

La persistance vous donne aussi une clé stable à enregistrer dans une base de données, ce qui est bien plus utile que de stocker un lien susceptible de pourrir.

Validez ce que vous avez obtenu

Des vérifications peu coûteuses évitent des erreurs coûteuses. Confirmez que le fichier n'est pas vide, que son nombre magique correspond à un format d'image et, éventuellement, que ses dimensions sont conformes à l'attendu. Rejeter une image corrompue ou tronquée à la frontière est bien préférable à la servir à un utilisateur.

Consignez la provenance

Stockez l'identifiant du modèle, le texte de l'instruction, la clé de l'image de référence et l'horodatage à côté de la sortie. Quand quelqu'un demandera trois semaines plus tard pourquoi une image donnée ressemble à cela, cette ligne sera la réponse — et elle rendra trivial le relancement d'une édition particulière.

Nouvelles tentatives et gestion des erreurs en production

Les appels de génération d'images échouent pour des raisons très différentes, et les confondre est un bug de production classique.

Distinguer les erreurs transitoires des erreurs définitives

  • Transitoires — délais d'attente, connexion réinitialisée, limitation de débit 429, réponses 5xx. La même requête retentée après une pause a de bonnes chances de réussir.
  • Définitives — 400 requête invalide, 401 clé incorrecte ou absente, 404 modèle inconnu, erreur de validation de la charge utile. Les retenter fait perdre du temps et de l'argent et retarde la vraie correction.

Ne retentez que la première catégorie. Pour la seconde, faites échouer la tâche immédiatement et exposez le message d'erreur — il vous indique presque toujours précisément quel champ pose problème.

Réessayer avec backoff et jitter

import random, time, requests

RETRYABLE = {429, 500, 502, 503, 504}

def call_with_retries(fn, attempts: int = 5, base: float = 1.0):
    last = None
    for i in range(attempts):
        try:
            return fn()
        except requests.HTTPError as e:
            status = e.response.status_code if e.response is not None else None
            if status not in RETRYABLE:
                raise
            last = e
        except (requests.Timeout, requests.ConnectionError) as e:
            last = e
        delay = base * (2 ** i) + random.uniform(0, 0.5)
        time.sleep(delay)
    raise RuntimeError("Nombre de tentatives épuisé") from last

Le backoff exponentiel évite de marteler un service déjà en difficulté ; le jitter empêche une flotte de workers de retenter en synchronisation. Limitez toujours le nombre de tentatives et la durée totale — une boucle non bornée est pire qu'un échec propre.

Respecter les limites de débit

En cas de 429, respectez tout indice de nouvelle tentative présent dans les en-têtes avant de backoffer. Si vous traitez de gros lots, ajoutez une limite de concurrence de votre côté au lieu de compter sur le serveur pour vous limiter.

Rendre les échecs visibles

  • Étiquetez les nouvelles tentatives avec un identifiant de tâche unique et consignez chaque tentative avec son résultat et sa durée.
  • Émettez des métriques sur le taux de nouvelles tentatives ; une montée lente est un signal précoce de dégradation en amont.
  • Après l'échec de la dernière tentative, déplacez la tâche vers une file de messages morts avec le corps complet de la réponse, pas seulement un message « failed ».

Idempotence et maîtrise des coûts

Une requête retentée peut avoir réussi côté serveur même si votre client n'a jamais vu la réponse. Si votre produit ne tolère pas les sorties en double, identifiez la tâche avec votre propre identifiant et réconciliez l'état avant une nouvelle tentative. Et comme les appels sont facturés à l'usage, méfiez-vous des boucles de nouvelle tentative qui gonflent discrètement la dépense — un consommateur bloqué qui retente indéfiniment est le bug le plus coûteux à cet égard.

Pitfalls courants et prochaines étapes

La plupart des difficultés d'intégration autour de flux-2/image-to-image proviennent d'une petite série d'erreurs. Avant de publier, vérifiez votre code sur ces points.

  • Instructions vagues. « Améliore-le » produit des résultats aléatoires ; « retire le texte de l'enseigne et conserve la forme de l'enseigne » produit des résultats exploitables. La précision est le plus grand levier de qualité.
  • Image de référence inadaptée. Un mauvais rapport d'aspect, une source floue ou un collage encombré ne seront pas sauvés par un meilleur prompt.
  • URL expirée. Un lien signé qui casse en cours de requête provoque des échecs qui ressemblent à des erreurs serveur. Prévoyez une validité suffisamment longue ou passez à base64.
  • Structure de réponse codée en dur. Plonger directement dans des clés imbriquées transforme un petit changement de schéma en panne. Utilisez des extracteurs défensifs avec des erreurs claires.
  • Absence de délai d'attente. Un timeout manquant immobilise un worker indéfiniment et masque le vrai problème.
  • Retenter des erreurs définitives. Un 400 ne se corrige pas tout seul. Lisez le message.
  • Sortie perdue. Si l'URL renvoyée est temporaire et que vous ne persistez pas l'image, vous n'avez rien.
  • Journalisation négligente des secrets et des prompts. Les clés ne doivent jamais apparaître dans les journaux ; les instructions fournies par les utilisateurs peuvent nécessiter une anonymisation selon votre domaine.

Prochaines étapes

Une fois le flux d'appel unique stabilisé, l'extension naturelle consiste à : encapsuler l'appel dans une tâche d'arrière-plan pour garder votre UI réactive ; stocker les paires instruction/réponse pour faire des tests A/B sur la formulation des prompts ; et, si les utilisateurs fournissent leurs propres images, ajouter une couche de modération ou de validation sur l'entrée. Parcourez la page modèle de flux-2/image-to-image et la documentation HiAPI pour voir les paramètres dont votre cas d'usage pourrait avoir besoin ensuite. Construisez le plus petit ensemble fonctionnel, mesurez-le, et laissez la qualité des instructions faire le gros du travail.

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