Blog

Tutoriel

Comment appeler flux-3-image-klein via l'API HiAPI : curl, Python et exemples de requêtes exploitables

Intégration concrète pour développeurs : de la première requête aux appels par lots fiables

Nov 12, 2026
Une image de couverture presque noire avec un champ de points vert menthe dont la densité augmente de gauche à droite, avec des points bleu sarcelle débordant sur le bord.
Modèle
flux-3-image-klein
Sur cette page

Ce que l'intégration de flux-3-image-klein exige réellement

Avant d'écrire la première ligne de code, déterminez exactement combien d'étapes séparent votre script d'une image générée. Pour flux-3-image-klein sur HiAPI, cette liste est courte : un point de terminaison, un justificatif d'authentification, un corps de requête JSON et un objet de réponse à analyser.

Voici le modèle mental à garder en tête :

  • Point de terminaison — une route HiAPI traite la génération d'images pour ce modèle. Toutes les requêtes y sont adressées ; le modèle est identifié dans le corps de la requête, et non par une URL distincte.
  • Justificatif d'authentification — une clé API émise depuis votre compte HiAPI. Elle est transmise à chaque appel via un en-tête HTTP. Traitez-la comme un mot de passe : lisez-la depuis une variable d'environnement, ne la codez jamais en dur dans un fichier susceptible d'être validé.
  • Corps de la requête — un petit objet JSON qui décrit le modèle, l'invite et quelques paramètres facultatifs influant sur la sortie (taille, indications liées au style, etc.).
  • Réponse — un objet JSON qui, une fois analysé, fournit la référence de l'image générée ainsi que les métadonnées renvoyées par l'API.

Deux prérequis méritent d'être vérifiés avant de commencer. Premièrement, assurez-vous que votre clé est active et dispose des autorisations de génération d'images — une clé valide pour une modalité ne l'est pas automatiquement pour une autre. Deuxièmement, gardez la documentation HiAPI actuelle ouverte dans un onglet. Les noms de paramètres, les tailles prises en charge et les champs de réponse peuvent changer ; la documentation est la seule source de vérité à laquelle vous devez vous référer, plutôt que votre mémoire ou un article de blog (y compris celui-ci).

Le reste de ce guide construit une requête, la porte en Python, puis la renforce pour des charges réelles. Si vous suivez les étapes dans l'ordre, chacune réutilise la précédente sans rien devoir réapprendre en cours de route.

Émettre une première requête fonctionnelle avec curl

Le moyen le plus rapide de confirmer qu'une intégration fonctionne est un appel curl dans le shell. Une fois une réponse réussie obtenue ici, tout le reste n'est que de l'empaquetage.

Exportez d'abord votre clé pour qu'elle n'apparaisse jamais en clair dans l'historique du shell :

export HIAPI_API_KEY="your-api-key-here"
export HIAPI_BASE_URL="https://api.hiapi.ai"

Envoyez ensuite une requête minimale :

curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-3-image-klein",
    "prompt": "un phare érodé sur une falaise au crépuscule, pose longue, brume douce"
  }'

Remarque sur l'URL : le chemin de base et la route exacts sont définis par la documentation HiAPI — utilisez le point de terminaison qui y figure, ne copiez pas le nom d'hôte depuis une capture d'écran tierce. Définissez une fois HIAPI_BASE_URL dans l'environnement, et chaque exemple suivant la réutilisera.

Voyons maintenant le rôle de chaque champ :

  • model identifie le modèle qui traite la tâche. Il doit correspondre exactement à la documentation ; une faute de frappe ici est la cause la plus fréquente de requêtes qui semblent valides mais ne renvoient aucun résultat utile.
  • prompt est votre description en langage naturel. Soyez précis sur le sujet, la composition, la lumière et l'ambiance — le modèle répond aux détails descriptifs, tandis qu'une invite vague produit des résultats imprévisibles et impossibles à déboguer.
  • Les en-têtes ne sont pas négociables : le jeton bearer sert à l'authentification, et Content-Type: application/json indique au serveur comment analyser le corps de la requête.

En cas de succès, vous recevez une réponse JSON contenant la référence de l'image générée (généralement une URL ou une ressource hébergée) ainsi que des métadonnées. Si vous voulez inspecter aussi les en-têtes de réponse, affichez d'abord la réponse complète avec curl sans suppression -sS, puis réduisez une fois la structure comprise. Enregistrez une vraie réponse dans un fichier — vous l'utiliserez comme fixture lors de l'écriture et des tests du client Python.

En cas d'échec, ne cédez pas à la tentation de modifier le corps de la requête au hasard. Vérifiez d'abord le code de statut et le corps du message d'erreur ; la section de dépannage plus loin dans ce guide associe chaque catégorie d'échec à un correctif précis.

Porter la requête en Python

Une fois curl fonctionnel, portez la requête en Python sans en changer la sémantique. Le but n'est pas de construire un framework — mais un petit client qui se comporte exactement comme la commande shell et s'étend facilement.

L'approche la plus propre consiste à placer le corps de la requête dans un emplacement partagé, afin que les versions curl et Python ne divergent jamais. Définissez-le comme un dictionnaire, sérialisez-le, et laissez un mince wrapper gérer les aspects HTTP.

import json
import os
import requests

BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]


def build_payload(prompt: str, **overrides) -> dict:
    payload = {
        "model": "flux-3-image-klein",
        "prompt": prompt,
    }
    payload.update(overrides)
    return payload


def generate_image(prompt: str, timeout: float = 60.0, **overrides) -> dict:
    response = requests.post(
        f"{BASE_URL}/v1/images/generations",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        data=json.dumps(build_payload(prompt, **overrides)),
        timeout=timeout,
    )
    response.raise_for_status()
    return response.json()


if __name__ == "__main__":
    result = generate_image(
        "un phare érodé sur une falaise au crépuscule, pose longue, brume douce"
    )
    print(json.dumps(result, indent=2))

Pourquoi cette structure est avantageuse :

  • build_payload est le seul endroit où le corps de la requête est assemblé. Ajoutez-y un paramètre, et le script d'exploration comme le code de production en bénéficient automatiquement.
  • raise_for_status() convertit immédiatement les échecs HTTP en exceptions, de sorte que vous ne prenez jamais accidentellement un corps de réponse d'erreur pour un résultat réussi.
  • Un timeout explicite évite le problème classique du blocage : une connexion stagnante bloque indéfiniment un thread de travail. Choisissez une valeur cohérente avec le budget de requête propre au service.
  • L'utilisation de variables d'environnement pour l'URL de base et la clé signifie que le même code s'exécute sans modification en préproduction et en production.

Exécutez-le et comparez la sortie à la réponse curl enregistrée précédemment. Elles doivent décrire la même structure. Si ce n'est pas le cas, le portage a introduit un bug — corrigez-le maintenant, car les divergences seront bien plus difficiles à repérer une fois les lots et les nouvelles tentatives ajoutés.

Gérer les paramètres de taille et de style

L'invite résout la majeure partie du problème, mais les paramètres qui influencent l'image — dimensions de sortie et indications liées au style — sont précisément là où l'intégration échoue discrètement. Deux règles vous protègent.

Placer les paramètres facultatifs dans un bloc explicite

Ne dispersez jamais de chaînes magiques dans le code. Étendez le constructeur de corps de requête avec des paramètres nommés et validez aux frontières :

def build_payload(prompt: str, size: str | None = None, style: str | None = None) -> dict:
    payload = {"model": "flux-3-image-klein", "prompt": prompt}
    if size:
        payload["size"] = size
    if style:
        payload["style"] = style
    return payload

Omettre complètement un paramètre est généralement préférable à l'envoi d'une chaîne vide ou d'un emplacement réservé. Si vous n'avez pas besoin de contrôler la taille, omettez-la et laissez le service appliquer sa valeur par défaut documentée.

Valider d'après la documentation, pas d'après des suppositions

C'est la partie que la plupart des tutoriels sautent : ne codez pas en dur une liste de tailles ou de valeurs de style « prises en charge » tirée d'un article de blog. Les valeurs prises en charge peuvent changer, et des constantes obsolètes deviennent des erreurs 400 à l'exécution difficiles à tracer. À la place :

  1. Lisez la référence actuelle des paramètres de flux-3-image-klein dans la documentation HiAPI, consignez les valeurs acceptables comme constante dans votre base de code, avec un commentaire indiquant la page de documentation et la date de vérification.
  2. Avant de construire une requête, validez l'entrée utilisateur ou appelante avec cette constante. Échouez rapidement avec un message d'erreur local clair, plutôt que d'envoyer sur le réseau une requête vouée à l'échec.
  3. Lorsqu'une requête renvoie une erreur de validation pour une valeur non prise en charge, mettez à jour la constante depuis la documentation, plutôt que de deviner une valeur voisine qui « semble correcte ».

Un petit tuple ALLOWED_SIZES plus une vérification d'appartenance coûtent presque rien, mais éliminent toute une catégorie de tickets de support. Même logique pour les indications de style : traitez-les comme un ensemble fermé que vous avez vérifié, et non comme une chaîne ouverte que le serveur tolérera peut-être.

Requêtes par lots et nouvelles tentatives en cas d'échec

Une seule requête dans un script n'est qu'une démonstration. Une charge réelle signifie des dizaines ou des milliers d'images, et c'est là que la discipline de la couche client importe. Placez la logique de traitement par lots et de nouvelle tentative dans le module client, plutôt que dans une boucle improvisée collée dans un notebook — vous voulez un seul endroit à observer et à ajuster.

Concurrence avec traçabilité

Un modèle simple est un pool de threads borné, où chaque tâche soumise renvoie à la fois l'entrée et le résultat :

from concurrent.futures import ThreadPoolExecutor, as_completed

def run_batch(prompts: list[str], max_workers: int = 4) -> list[dict]:
    results = []
    with ThreadPoolExecutor(max_workers=max_workers) as pool:
        futures = {pool.submit(generate_image, p): p for p in prompts}
        for future in as_completed(futures):
            prompt = futures[future]
            try:
                results.append({"prompt": prompt, "ok": True, "data": future.result()})
            except Exception as exc:
                results.append({"prompt": prompt, "ok": False, "error": str(exc)})
    return results

Deux propriétés importantes ici. Premièrement, chaque résultat est associé à son invite, de sorte qu'un échec partiel est attribuable plutôt que mystérieux. Deuxièmement, max_workers est le bouton que vous contrôlez — commencez par une valeur prudente, observez le taux d'erreur, et n'augmentez la concurrence qu'après des exécutions de lots sans erreur. Marteler le point de terminaison avec un parallélisme illimité est le moyen le plus rapide de transformer une intégration saine en incident de limitation de débit.

Nouvelles tentatives avec backoff

Ne réessayez que ce qui est sûr : erreurs réseau transitoires, délais d'attente et réponses de limitation de débit. Ne réessayez pas les erreurs de validation — la requête échouera de la même manière à chaque fois et vous ne ferez que gaspiller du quota.

import time

def generate_with_retry(prompt: str, attempts: int = 3, **overrides) -> dict:
    delay = 1.0
    for attempt in range(1, attempts + 1):
        try:
            return generate_image(prompt, **overrides)
        except requests.HTTPError as exc:
            status = exc.response.status_code if exc.response is not None else None
            if status is not None and 400 <= status < 500 and status != 429:
                raise
            if attempt == attempts:
                raise
        except requests.Timeout:
            if attempt == attempts:
                raise
        time.sleep(delay)
        delay *= 2
    raise RuntimeError("unreachable")

Journalisez une ligne par tentative, avec l'identifiant de l'invite, le numéro de tentative et le statut. Lorsqu'une exécution par lots se passe mal, c'est cette ligne de journal qui vous dit si vous avez affaire à une instabilité transitoire ou à un problème systémique de corps de requête.

Diagnostiquer les erreurs de requête courantes

La plupart des échecs de la première semaine ne viennent pas du modèle — mais du pipeline. Voici les catégories que vous rencontrerez le plus probablement, avec le correctif précis de chacune.

401 / 403 — Authentification et autorisation

Symptôme : rejet immédiat avant toute génération. Cause : en-tête Authorization absent, jeton bearer mal formaté, clé expirée ou révoquée, ou caractères blancs collés dans la variable d'environnement. Correctif : affichez les premiers et derniers caractères de la clé réellement envoyée (n'affichez jamais la clé complète), vérifiez que l'en-tête est au format Bearer <key> avec exactement un espace, et confirmez que la clé est active dans votre compte HiAPI. Si la clé fonctionne avec curl mais pas en Python, la différence réside presque toujours dans la façon dont l'en-tête est assemblé.

400 — Validation du corps de requête

Symptôme : la requête est comprise mais rejetée à cause d'un champ. Cause : faute de frappe dans model, prompt manquant, valeur de size ou de style non prise en charge, ou type incorrect (un nombre envoyé là où une chaîne est attendue). Correctif : comparez caractère par caractère votre corps sérialisé — json.dumps(build_payload(...)) — avec le schéma de la documentation. Validez localement les paramètres facultatifs avec les constantes dérivées de la documentation, afin qu'aucune mauvaise valeur ne quitte votre processus.

404 — Route incorrecte

Symptôme : le point de terminaison lui-même est introuvable. Cause : chemin mal orthographié, URL de base obsolète, ou incohérence de barre oblique en début ou fin lors de la concaténation des fragments d'URL. Correctif : construisez l'URL à partir d'une seule constante et vérifiez-la par rapport à la référence des points de terminaison de la documentation HiAPI, plutôt que par rapport à un extrait de code copié.

429 — Limitation de débit

Symptôme : les requêtes commencent à réussir, puis échouent par lots sous charge. Correctif : réduisez max_workers, respectez la stratégie de backoff déjà présente dans le wrapper de nouvelle tentative, et traitez les 429 comme des erreurs transitoires. Si les 429 persistent à faible concurrence, il faut examiner les limites ou les schémas d'utilisation de votre compte — pas modifier le code.

Délais d'attente et réinitialisations de connexion

Symptôme : l'appel reste bloqué longtemps, ou des exceptions ReadTimeout surviennent en cours de lot. Cause : délai d'attente client trop agressif, réseau instable, ou un gros lot qui sature le pool de connexions. Correctif : définissez un délai d'attente explicite mais réaliste pour chaque requête, réessayez les délais d'attente avec backoff, et maintenez une concurrence modérée. Ne supprimez jamais le délai d'attente pour « faire fonctionner les choses » — cela transformerait un échec visible en blocage invisible.

Succès, mais image incorrecte

C'est un problème d'invite, pas un problème d'API. Des invites vagues, des indications de style contradictoires, et des invites en conflit avec un size explicite produisent des sorties inattendues. Affinez d'abord la description de l'invite ; ne réexaminez les paramètres qu'ensuite.

Liste de vérification avant la mise en production

Avant de diriger le trafic de production vers flux-3-image-klein, parcourez cette liste. Cela ne prend que quelques minutes, mais permet de détecter des défaillances coûteuses en production.

  • Justificatifs d'authentification — la clé est chargée depuis une variable d'environnement ou un gestionnaire de secrets, jamais validée dans le dépôt ; confirmez qu'elle permet la génération d'images sur le compte que vous comptez facturer.
  • Point de terminaison — l'URL de base et la route proviennent littéralement de la documentation HiAPI actuelle et sont stockées comme constante unique.
  • Structure du corps de requête — le nom du modèle est orthographié exactement comme dans la documentation, l'invite est toujours présente et non vide, les paramètres facultatifs sont omis lorsqu'inutilisés et validés localement lorsqu'ils sont définis.
  • Valeurs des paramètres — vos constantes de size et de style ont été vérifiées par rapport à la documentation à la date indiquée en commentaire, avec un plan de revérification après mise à jour de l'API.
  • Stratégie de nouvelle tentative — les erreurs transitoires et les délais d'attente sont réessayés avec backoff, les erreurs client échouent rapidement, et le nombre de tentatives est plafonné.
  • Concurrence — max_workers est défini prudemment et n'est augmenté qu'après des exécutions de lots sans erreur.
  • Délais d'attente — explicites pour chaque requête ; aucun chemin ne permet à un appel bloqué de bloquer indéfiniment un thread de travail.
  • Observabilité — une ligne de journal par tentative, avec identifiant de l'invite, numéro de tentative, statut et latence ; dans la sortie de lot, le résultat de chaque requête est attribuable.
  • Artefacts d'échec — au moins une vraie réponse réussie et une vraie réponse d'erreur sont conservées comme fixtures de test.

Si un élément n'est pas coché, le corriger maintenant coûte moins cher que de déboguer à deux heures du matin. Une fois la liste entièrement verte, vous disposez d'un petit client observable et extensible, plutôt que d'un script que vous n'oseriez pas toucher. Pour la référence de paramètres faisant autorité et toute mise à jour des points de terminaison, mettez la documentation HiAPI en favori et considérez-la comme la référence finale.

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