Comment utiliser flux-2-klein-4b/image-to-image via l'API hiapi

FLUX.2 [klein] 4B est un modèle d'édition d'image compact et rapide proposé par Black Forest Labs : donnez-lui une image de référence et une instruction en langage naturel, et il renvoie une image éditée jusqu'à 4 MP. Sur hiapi, il s'exécute via la même Unified Async API que tous les autres modèles — créez une tâche avec POST /v1/tasks, puis récupérez le résultat par interrogation répétée ou via un callback. Ce guide couvre la structure exacte de la requête, des exemples curl/Python fonctionnels et la manière de l'intégrer en production.

Ce dont vous avez besoin

• Une clé API hiapi. Elle s'obtient depuis le dashboard — la clé ressemble à sk-... et se place dans l'en-tête Authorization: Bearer.
• Une URL d'image de référence accessible publiquement (jpeg, png ou webp — svg non pris en charge). Les images dépassant 4 MP sont automatiquement réduites à 4 MP.
• Le tarif actuel de flux-2-klein-4b/image-to-image est dégressif selon la résolution (de 0,25 MP à 4 MP) — consultez hiapi pricing pour les prix en temps réel, ne codez pas les tarifs en dur ici.

Exemple minimal fonctionnel

L'identifiant du modèle est flux-2-klein-4b/image-to-image — utilisez-le exactement tel quel (avec la barre oblique), comme valeur de model (pas dans le chemin de l'URL). Tous les modèles hiapi partagent le même endpoint ; seuls les champs de l'objet input varient selon le modèle.

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2-klein-4b/image-to-image",
    "input": {
      "prompt": "Keep the subject and camera angle. Replace the background with a deep-blue studio gradient and add soft rim lighting.",
      "image_urls": ["https://your-cdn.example.com/product-shot.jpg"],
      "resolution": "2 MP",
      "aspect_ratio": "16:9"
    }
  }'

Cette requête renvoie immédiatement un taskId — la génération est asynchrone :

{"code": 0, "message": "success", "data": {"taskId": "task_..."}}

Interrogez le résultat :

curl "https://api.hiapi.ai/v1/tasks/task_..." \
  -H "Authorization: Bearer sk-YOUR_API_KEY"

Lorsque status passe à "success", l'image éditée se trouve dans data.output[0].url. Cette URL est temporaire (elle comporte un expireAt), donc téléchargez ou ré-hébergez immédiatement le fichier — ne stockez pas ce lien direct tel quel.

Même flux en Python :

import time
import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": "Bearer sk-YOUR_API_KEY",
    "Content-Type": "application/json",
}

def create_task(prompt: str, image_url: str) -> str:
    payload = {
        "model": "flux-2-klein-4b/image-to-image",
        "input": {
            "prompt": prompt,
            "image_urls": [image_url],
            "resolution": "2 MP",
            "aspect_ratio": "16:9",
        },
    }
    resp = requests.post(API, headers=HEADERS, json=payload, timeout=30)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]

def wait_task(task_id: str, timeout_s: int = 300, poll_s: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30)
        task = r.json()["data"]
        if task["status"] == "success":
            return task
        if task["status"] == "fail":
            raise RuntimeError(f"task {task_id} failed: {task.get('error')}")
        time.sleep(poll_s)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")

task_id = create_task(
    "Keep the subject and camera angle. Replace the background with a deep-blue "
    "studio gradient and add soft rim lighting.",
    "https://your-cdn.example.com/product-shot.jpg",
)
result = wait_task(task_id)
print(result["output"][0]["url"])

Paramètres de requête

flux-2-klein-4b/image-to-image accepte un schéma d'entrée strict — les champs supplémentaires non listés ici sont rejetés avec un code 400 :

Champ	Obligatoire	Description
prompt	Oui	Description en langage naturel de l'édition à appliquer.
image_urls	Oui	Tableau contenant exactement une URL d'image de référence. En fournir plusieurs renvoie maxItems: got N, want 1.
resolution	Non	Valeurs possibles : 0.25 MP, 0.5 MP, 1 MP (par défaut), 2 MP, 4 MP. Utilisez 0,25/0,5 MP pour des brouillons peu coûteux et 2/4 MP pour la sortie finale.
aspect_ratio	Non	Valeurs possibles : match_input_image (par défaut), 1:1, 16:9, 9:16, 3:2, 2:3, 4:3, 3:4, 5:4, 4:5, 21:9, 9:21.
seed	Non	Entier, pour obtenir une sortie reproductible entre des requêtes par ailleurs identiques.
output_format	Non	jpg (par défaut), png ou webp.
output_quality	Non	Entier, qualité de compression pour jpg/webp (par défaut 95).

Ce modèle n'a pas de champ size ni n — ce sont des conventions d'autres fournisseurs que ce schéma ne reconnaît pas. Chaque modèle hiapi possède son propre ensemble de champs ; consultez donc la page de référence du modèle avant de porter une requête conçue pour un autre modèle.

Considérations pour la production

Privilégiez les callbacks à l'interrogation répétée. Ajoutez un objet callback au niveau supérieur et hiapi notifiera votre service, au lieu que vous fassiez des appels en boucle :

{
  "model": "flux-2-klein-4b/image-to-image",
  "input": { "prompt": "...", "image_urls": ["..."] },
  "callback": { "url": "https://your-domain.com/hiapi/callback", "when": "final" }
}

when n'accepte que "final" — une seule notification est envoyée lorsque la tâche atteint un état terminal (success ou fail), et non un flux de progression. Traitez le callback comme un signal de réveil : à sa réception, vous devez tout de même faire un GET /v1/tasks/<taskId> pour lire l'état faisant foi, et rendre votre gestionnaire idempotent sur le taskId pour éviter les doublons de livraison.

Idempotence. Persistez le taskId dès que create_task le renvoie, avant de commencer à interroger ou à attendre un callback. Si le processus plante pendant l'attente, reprenez au redémarrage avec GET /v1/tasks/<taskId> plutôt que de recréer la tâche — la création d'une tâche est un événement facturé, tandis que le GET peut être répété gratuitement.

Gestion des erreurs. Une clé invalide ou non autorisée renvoie un HTTP 401 avec un corps de réponse structuré :

{
  "error": {
    "code": "permission_denied",
    "message": "This API key cannot use the selected model. Please check permissions or use another key. If the issue persists, contact support with request ID: ...",
    "request_id": "...",
    "type": "hiapi_error"
  }
}

Notez le request_id — l'équipe de support peut s'en servir pour retrouver l'appel exact. Un input mal formé (prompt/image_urls manquants, valeur d'aspect_ratio non prise en charge ou champ supplémentaire non reconnu) renvoie un code 400 avec error_code: "INVALID_REQUEST" et un message indiquant le champ problématique ; corrigez le corps de la requête plutôt que de réessayer tel quel.

Pour aller plus loin

• Référence du modèle image-vers-image FLUX.2 [klein] 4B — documentation complète des paramètres et corps de requête d'exemple.
• Référence du modèle texte-vers-image FLUX.2 [klein] 4B — la variante texte-vers-image correspondante, sans image de référence.
• hiapi pricing — coût actuel par image, dégressif selon la résolution.
• Vue d'ensemble de l'Unified Async API — le contrat POST /v1/tasks / GET /v1/tasks/:id partagé par tous les modèles de la plateforme.

Questions fréquentes

Quels formats d'image image_urls accepte-t-il ? jpeg, png ou webp. svg n'est pas pris en charge. Les images dépassant 4 MP sont automatiquement réduites à 4 MP avant l'édition.

Puis-je fournir plusieurs images de référence ? Non — image_urls sur ce modèle est limité à exactement un élément. En fournir davantage renvoie un code 400 (maxItems: got N, want 1).

Pourquoi ma requête est-elle rejetée avec le message "additional properties ... not allowed" ? Le schéma est strict : tout champ absent du tableau de paramètres ci-dessus (par exemple les conventions d'autres fournisseurs comme size, n ou strength) déclenche un code 400. Consultez la référence du modèle pour connaître l'ensemble exact des champs acceptés.

Comment conserver le rapport d'aspect de l'image d'origine ? Définissez aspect_ratio sur match_input_image — c'est aussi la valeur par défaut si vous omettez complètement le champ.

Quelle est la différence entre flux-2-klein-4b/image-to-image et la variante 9B ? Les deux partagent le même schéma de requête (prompt, image_urls, resolution, aspect_ratio, seed, output_format, output_quality). La variante 9B sacrifie un peu de vitesse et de coût pour un meilleur réalisme, un meilleur rendu du texte et davantage de détails — utilisez 4B lorsque vous itérez rapidement et à moindre coût, et 9B lorsque l'édition doit tenir la route sur les détails fins.

Ai-je besoin d'une URL de callback, ou l'interrogation répétée suffit-elle ? L'interrogation via GET /v1/tasks/:id convient pour le développement local, les tâches à faible volume, ou comme solution de repli si un callback est manqué. Pour le trafic de production, les callbacks évitent la surcharge d'une boucle d'interrogation pour chaque requête.