Comment utiliser flux-2/image-to-image via l'API hiapi : curl, Python et exemples de requêtes disponibles

En bref

• De quoi s'agit-il : la solution disponible pour appeler l'API flux-2/image-to-image sur hiapi — créer une tâche, interroger son état, télécharger le résultat.
• Point de terminaison : utilisez POST https://api.hiapi.ai/v1/tasks avec "model": "flux-2/image-to-image", puis GET /v1/tasks/<taskId> jusqu'à ce que la tâche atteigne un état terminal.
• Champs d'entrée obligatoires (les quatre) : prompt, image_urls (1 à 8 URL publiques — c'est la fonctionnalité multi-images de référence), aspect_ratio et resolution (1K ou 2K).
• Le schéma est strict. Des champs comme strength ou fidelity n'existent pas et sont rejetés avec un 400. La fidélité est contrôlée par vos images de référence, votre prompt et la resolution — pas par un réglage dédié.

Ce que vous allez construire et ce qu'il vous faut préparer

Objectif : envoyer une ou plusieurs images de référence accompagnées d'un prompt texte à flux-2 et récupérer une image éditée/retouchée téléchargeable — avec curl ou Python, sans SDK.

Prérequis :

1. Une clé API hiapi — à créer dans la console hiapi. La clé ressemble à sk-... et se place dans l'en-tête Authorization: Bearer.
2. Au moins une URL d'image accessible publiquement à utiliser comme image de référence. L'API récupère les image_urls côté serveur, donc les liens localhost ou les URL de buckets privés ne fonctionnent pas — utilisez un bucket public, un CDN ou une URL pré-signée.
3. curl, ou Python 3.8+ avec requests (pip install requests).

Schéma de la requête

flux-2/image-to-image s'exécute sur l'interface de tâches unifiée de hiapi. L'objet input accepte exactement les champs suivants :

Champ	Type	Obligatoire	Description
prompt	string	oui	Ce qu'il faut modifier ou générer. Au moins 3 caractères.
image_urls	string[]	oui	1 à 8 URL d'images publiques. Plus d'une image = multi-référence : flux-2 fusionne l'identité, le produit ou les indices de style entre toutes les images de référence.
aspect_ratio	string	oui	L'un des suivants : 1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3 ou auto (suit l'image de référence).
resolution	string	oui	1K ou 2K.

Tout autre champ sera rejeté. Par exemple, envoyer un champ strength ou fidelity renvoie :

{
  "code": 400,
  "error_code": "INVALID_REQUEST",
  "message": "invalid input: <root>: additional properties 'fidelity', 'strength' not allowed"
}

À retenir : le mode image-to-image de flux-2 n'a pas de réglage de force de débruitage. La fidélité de la sortie vis-à-vis de l'image de référence (édition « haute fidélité » vs. retouche libre) dépend de la façon dont vous rédigez le prompt — par exemple « Garde le produit, son étiquette et ses proportions strictement identiques à l'image de référence ; remplace uniquement l'arrière-plan » — ainsi que de l'usage de resolution: "2K" pour les travaux exigeant des détails.

Exemple minimal fonctionnel : curl

Étape 1 — créer la tâche :

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2/image-to-image",
    "input": {
      "prompt": "Place this product on a white marble countertop with soft morning light, keep the product itself unchanged",
      "image_urls": ["https://your-cdn.example.com/product.jpg"],
      "aspect_ratio": "1:1",
      "resolution": "2K"
    }
  }'

Une création réussie renvoie l'ID de tâche dans data.taskId.

Étape 2 — interroger jusqu'à l'achèvement :

curl -s https://api.hiapi.ai/v1/tasks/TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

Tant que data.status n'est pas terminal, continuez à interroger toutes les quelques secondes. Lorsque "status": "success", l'URL de l'image se trouve dans data.output[0].url.

Étape 3 — télécharger le résultat immédiatement :

curl -s -o result.jpg "OUTPUT_URL"

Les URL de sortie portent un horodatage expireAt — elles sont temporaires. Téléchargez les octets dès que la tâche réussit (ou copiez-les dans votre propre stockage) ; ne hotlinkez pas directement les sorties de tâches en production.

Exemple minimal fonctionnel : Python

Un script complet — création, interrogation, téléchargement — utilisant uniquement requests :

import time
import requests

API_KEY = "sk-YOUR_KEY"
BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

def create_task() -> str:
    resp = requests.post(BASE, headers=HEADERS, json={
        "model": "flux-2/image-to-image",
        "input": {
            "prompt": ("Combine the person from the first image with the jacket "
                       "from the second image, studio lighting, neutral backdrop"),
            "image_urls": [
                "https://your-cdn.example.com/person.jpg",
                "https://your-cdn.example.com/jacket.jpg",
            ],
            "aspect_ratio": "3:4",
            "resolution": "2K",
        },
    }, timeout=30)
    body = resp.json()
    task_id = (body.get("data") or {}).get("taskId")
    if not task_id:
        raise RuntimeError(f"create failed: {body}")
    return task_id

def wait_task(task_id: str, timeout_s: int = 600, poll_s: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        task = requests.get(f"{BASE}/{task_id}", headers=HEADERS,
                            timeout=30).json().get("data") or {}
        status = task.get("status")
        if status == "success":
            return task
        if status == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        time.sleep(poll_s)
    raise TimeoutError(f"task {task_id} still running after {timeout_s}s")

task_id = create_task()
print("task:", task_id)
task = wait_task(task_id)
url = task["output"][0]["url"]          # URL temporaire — à sauvegarder immédiatement
img = requests.get(url, timeout=120).content
with open("result.jpg", "wb") as f:
    f.write(img)
print("saved result.jpg,", len(img), "bytes")

Remarquez ici l'usage de image_urls avec deux images — c'est l'utilisation concrète de la multi-référence. Jusqu'à 8 images de référence sont acceptées ; le modèle les combine (personne + vêtement, produit + style d'arrière-plan, personnage + référence de pose, etc.).

Bonnes pratiques de production

Préférez les callbacks à l'interrogation. Pour tout scénario au-delà d'un script, enregistrez un callback lors de la création de la tâche afin que hiapi pousse le résultat terminal à votre service :

{
  "model": "flux-2/image-to-image",
  "input": { "...": "..." },
  "callback": { "url": "https://your-app.example.com/hooks/hiapi", "when": "final" }
}

Avec "when": "final", vous ne recevez qu'un seul POST lorsque la tâche atteint un état terminal. Règle empirique : l'interrogation convient au CLI, au traitement par lots et à tout scénario à durée de vie courte ; le callback convient mieux aux applications grand public, car maintenir une boucle d'interrogation par worker pour chaque image ne passe pas à l'échelle. Si vous ne pouvez pas exposer de point de terminaison de callback public, alors interrogez — en espaçant simplement l'intervalle au-delà de 5 secondes.

Rendez les nouvelles tentatives sûres. Traitez la création de tâche comme l'effet de bord qu'elle est : avant d'agir sur le résultat, enregistrez le taskId renvoyé dans votre propre suivi de jobs ; lors d'une nouvelle tentative, vérifiez à nouveau l'état de la tâche déjà enregistrée plutôt que de créer aveuglément une nouvelle tâche (chaque création réussie est facturée séparément). Si votre exécuteur de jobs peut se déclencher deux fois, dédupliquez d'abord selon votre propre ID de job.

Gérez les erreurs que vous rencontrerez réellement :

• 401 permission_denied — clé incorrecte, ou clé sans autorisation d'utiliser ce modèle. Corps de la réponse :

  {"error": {"code": "permission_denied",
             "message": "This API key cannot use the selected model. ...",
             "type": "hiapi_error"}}
  

  Vérifiez la clé dans la console ; notre liste de vérification pour clé API invalide couvre les causes courantes.

• 400 INVALID_REQUEST — violation du schéma. Le message liste en une fois tous les champs en violation (champs obligatoires manquants, valeurs d'énumération erronées, champs supplémentaires inconnus), donc lisez-le en entier plutôt que de corriger un seul champ à chaque tentative.

• Tâche status: "fail" — la tâche a été acceptée mais la génération a échoué ; l'erreur se trouve dans data.error. Gérez-la dans le chemin d'interrogation/callback, pas au moment de la création.

• URL de sortie expirée — si le téléchargement renvoie un 4xx quelques minutes après le succès, c'est que vous avez trop attendu. Revérifiez expireAt et téléchargez toujours immédiatement.

Lectures associées

• Page du modèle flux-2/image-to-image — paramètres et tarif actuel
• Page du modèle flux-2/text-to-image — même famille, sans image de référence
• flux-2 pour les images produits e-commerce — solution de bout en bout côté text-to-image
• FLUX 1.1 Pro sur hiapi — comparaison avec l'option de génération précédente
• Tarification hiapi — coût par image selon la résolution

Questions fréquentes

Combien d'images de référence puis-je transmettre à flux-2 image-to-image ? 1 à 8, sous forme d'URL publiques dans image_urls. Au-delà de 8, la validation échoue (maxItems: got N, want 8).

Existe-t-il un paramètre strength ou fidelity ? Non. Le schéma d'entrée accepte uniquement prompt, image_urls, aspect_ratio et resolution ; les champs inconnus sont rejetés avec un 400. Contrôlez la fidélité par la formulation du prompt (précisez explicitement ce qui doit rester inchangé) et utilisez 2K lorsque les détails comptent.

Quelles résolutions et quels ratios d'aspect sont pris en charge ? resolution vaut 1K ou 2K. aspect_ratio vaut l'un des suivants : 1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3 ou auto — auto suit votre image de référence, ce qui est généralement souhaité pour l'édition.

Puis-je envoyer une image en base64 plutôt qu'une URL ? Non — image_urls accepte des URL, et elles doivent être accessibles publiquement pour que l'API puisse les récupérer. Téléchargez d'abord vers un bucket ou un CDN, puis transmettez l'URL générée (les URL pré-signées fonctionnent).

Combien coûte chaque image avec flux-2 image-to-image ? Le prix varie selon la résolution — consultez la page du modèle flux-2/image-to-image et la page de tarification pour le tarif actuel par image.

Combien de temps les URL des images générées restent-elles valides ? Les URL de sortie sont temporaires et contiennent un champ expireAt. Téléchargez les octets de l'image et stockez-les vous-même dès que la tâche réussit.

Quelle différence entre flux-2/image-to-image et flux-2/text-to-image ? Même famille de modèles, modes différents : text-to-image génère uniquement à partir du prompt, tandis que image-to-image nécessite 1 à 8 images de référence et édite ou combine à partir de celles-ci. Leurs schémas d'entrée diffèrent, donc les corps de requête ne sont pas interchangeables.