Blog

Tutoriel

Comment utiliser flux-3 via l'API HiAPI : curl, Python et exemples de requêtes fonctionnelles

Nov 10, 2026
Image de couverture : des plaques de verre translucides se chevauchent, réfractant un fond clair en bandes d'un bleu froid, dans une composition géométrique abstraite aux espaces négatifs équilibrés.
Sur cette page

Ce que vous obtenez en utilisant flux-3 via HiAPI

flux-3 est un modèle de génération d'images capable de traiter aussi bien le text-to-image que l'image-to-image. Si vous construisez une fonctionnalité produit, un outil de conception ou un pipeline interne, la partie vraiment intéressante n'est souvent pas le modèle lui-même — mais la propreté avec laquelle vous pouvez le placer derrière une interface stable et prévisible, et maintenir cet état lorsque les besoins évoluent.

C'est précisément là que réside la valeur d'une plateforme API agrégatrice. Appeler flux-3 via HiAPI signifie que vous :

  • N'intégrez qu'une seule fois. Une seule URL de base, un seul mode d'authentification, et une structure de requête et de réponse cohérente entre les modèles que vous utilisez. Changer ou comparer des modèles ne demande plus qu'un changement de configuration, pas une réécriture du code.
  • Économisez le travail d'infrastructure. Pas d'hébergement de modèle, pas de dimensionnement GPU, pas de gestion des démarrages à froid de votre côté. Vous envoyez une requête HTTP et traitez la réponse.
  • Centralisez la gestion des identifiants. Une seule clé API à émettre, faire tourner et restreindre, plutôt qu'une relation distincte avec chaque fournisseur en amont.
  • Bénéficiez d'une sémantique d'erreur unifiée. Quel que soit le modèle derrière l'appel, les codes de statut et les enveloppes d'erreur sont identiques, ce qui permet de réutiliser la logique de nouvelle tentative et d'alerte.

Concrètement pour flux-3, cela signifie que vous pouvez passer d'un prototype dans un notebook à un point de terminaison de production sans modifier la structure du code client. Les deux modes de génération — text-to-image et image-to-image — partagent la même structure de requête, donc les prendre en charge ne dépend que des champs que vous remplissez, et non du SDK que vous importez.

Les conventions suivantes s'appliquent tout au long de cet article :

  • URL de base : le point de terminaison de l'API HiAPI indiqué dans la console de votre compte.
  • Authentification : un jeton bearer transmis dans l'en-tête Authorization.
  • Type de contenu : application/json pour le corps de la requête ; les entrées d'image sont fournies sous forme d'URL ou de données encodées en base64, selon les limites de taille de votre charge utile.

Gardez votre clé dans une variable d'environnement — ne la validez jamais dans le contrôle de source. Les exemples ci-dessous lisent la clé depuis HIAPI_API_KEY et l'identifiant de modèle depuis FLUX_MODEL, de sorte que vous pouvez ajuster sans modifier le code.

Le décor est planté ; la section suivante décompose le corps de la requête lui-même.

Anatomie d'une requête : text-to-image et image-to-image

Un appel flux-3 se décompose logiquement en trois parties : le chemin du point de terminaison, les en-têtes d'authentification et un corps JSON. C'est dans le corps que les deux modes diffèrent, et comprendre cette différence vous permet de réutiliser un seul client pour les deux.

Le squelette commun

Chaque requête contient des champs sous une forme ou une autre :

  • model — le modèle à appeler ; ici, votre identifiant flux-3.
  • input — l'objet portant les instructions de génération.
  • input.prompt — une description en langage naturel de ce que vous voulez. Obligatoire dans les deux modes.
  • Paramètres de génération optionnels — comme les dimensions de sortie, le rapport d'aspect ou le nombre d'étapes, selon les capacités exposées par le modèle. Ne définissez que ce dont vous avez besoin ; les valeurs par défaut sont généralement suffisamment raisonnables.
  • Contrôle asynchrone optionnel — des indicateurs ou des callbacks qui modifient l'exécution et la livraison des tâches (détaillés dans la section suivante).

Text-to-image

En mode text-to-image, prompt est le seul champ substantiel. Vous décrivez l'image, vous contraignez éventuellement la géométrie de sortie, puis vous soumettez. Comme il n'y a pas d'image source, le modèle dispose de la plus grande liberté — ce qui signifie aussi que la qualité du prompt détermine la qualité de la sortie.

Une habitude utile : rédigez le prompt comme vous brieferiez un illustrateur humain. Écrivez dans l'ordre : sujet, composition, éclairage, style et toute contrainte ferme (par exemple « aucun texte dans l'image », « sujet centré »). Un prompt vague produit un résultat médiocre quel que soit le nombre d'étapes.

Image-to-image

En mode image-to-image, vous ajoutez un champ d'image source en plus du prompt ; le prompt décrit alors une transformation par rapport à cette entrée, plutôt qu'une scène construite à partir de zéro. Selon l'interface du modèle, cela peut signifier fournir une URL d'image ou une charge utile d'image encodée, plus tout paramètre d'intensité ou de guidage contrôlant dans quelle mesure la sortie s'écarte de l'image source.

Pour votre client API, l'impact pratique est minime : même point de terminaison, même authentification, même objet input — juste un champ de plus. C'est précisément l'objectif de conception. Votre fonction generate() doit accepter une image source optionnelle et gérer la branche en interne, afin que l'appelant n'ait jamais besoin de savoir quel mode il a déclenché.

Structure de la réponse

La réponse doit contenir un identifiant de tâche et, une fois terminée, l'emplacement de l'image générée. Traitez cet emplacement comme une valeur opaque : récupérez-la ou stockez-la, mais ne faites aucune hypothèse d'analyse sur son contenu. Certaines réponses sont immédiates, d'autres sont des handles de tâche — c'est précisément pourquoi le traitement asynchrone doit être intégré à la conception dès le premier jour.

Paramètres et modes asynchrones

Choisir les paramètres de génération

Les paramètres de génération sont un compromis entre qualité, latence et coût. Quelques principes s'appliquent à la plupart des modèles d'image, y compris flux-3 :

  • Résolution et rapport d'aspect influencent à la fois l'utilité de la sortie et la consommation de calcul. Générez à la taille à laquelle vous livrerez réellement ; réduire une grande image gaspille le budget, agrandir une petite image gaspille le rendu.
  • Étapes ou contrôle de qualité améliorent la fidélité jusqu'à un certain point, puis plafonnent. Mesurez avec un prompt fixe pour trouver ce point d'inflexion et arrêtez-vous là.
  • Contrôle de déterminisme (si disponible) est important pour la reproductibilité. Si vous devez rejouer le même résultat pour le QA ou le support utilisateur, enregistrez les paramètres avec la sortie.

Ne devinez pas les noms de paramètres ni les plages acceptables — lisez la documentation du modèle dans la console et faites-y foi. Si un champ est rejeté, la réponse d'erreur vous indiquera lequel.

Synchrone vs. asynchrone

La génération d'images n'est pas instantanée. Il existe deux modes d'exécution :

Synchrone (bloquant). Vous envoyez la requête et maintenez la connexion jusqu'à ce que l'image soit prête. C'est simple, adapté aux tâches courtes, aux scripts et aux outils interactifs où l'utilisateur regarde une animation de chargement. Mais c'est aussi fragile : les fonctions serverless, les équilibreurs de charge et les clients mobiles ont tous des limites de délai, et un rendu long finira par en heurter une.

Asynchrone (basé sur des tâches). Vous soumettez la requête, recevez immédiatement un identifiant, puis interrogez le point de terminaison de statut ou recevez un callback jusqu'à ce que la tâche signale son achèvement. Choisissez ce mode dans les cas suivants :

  • Runtimes serverless et edge avec des limites de durée d'exécution strictes.
  • Tâches de traitement par lots nécessitant de soumettre de nombreux rendus en parallèle.
  • Tout flux d'interaction utilisateur qui souhaite rendre la main immédiatement et diffuser la progression en continu.

Concevez le client autour de l'asynchrone, puis enveloppez les cas simples dans une méthode de commodité synchrone. L'inverse — forcer l'asynchrone dans un client bloquant — donne rarement de bons résultats.

Lors de l'interrogation, utilisez un backoff exponentiel plafonné plutôt qu'une boucle serrée fixe, fixez une limite de temps d'attente totale, et traitez les tâches qui n'atteignent jamais un état terminal comme des erreurs méritant une alerte.

Une requête curl fonctionnelle

Commencez depuis le terminal ; une fois l'échange HTTP brut clarifié, la version code devient simple.

1. Configurer l'environnement

export HIAPI_API_KEY="your-key-here"
export FLUX_MODEL="your-flux-3-model-id"
export HIAPI_BASE="https://your-hiapi-endpoint"

Placez l'identifiant du modèle dans une variable — changer de modèle plus tard ne demandera qu'une seule ligne.

2. Envoyer une requête text-to-image

curl -sS -X POST "$HIAPI_BASE/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$FLUX_MODEL"'",
    "input": {
      "prompt": "A minimal studio photograph of a ceramic mug on a concrete surface, soft side light, shallow depth of field"
    }
  }'

L'indicateur -sS garde la sortie propre tout en affichant toujours les erreurs. Avant d'exécuter, vérifiez le chemin exact par rapport au point de terminaison documenté dans la console — les chemins sont versionnés, faites foi à la documentation.

3. Lire le contenu renvoyé

Faites passer la réponse par un formateur pour la rendre lisible :

... | python -m json.tool

Surveillez deux choses : l'identifiant de tâche, et l'emplacement de l'image ou le champ de statut qui vous indique que la tâche est toujours en cours. Si vous voyez un statut plutôt qu'une image, vous êtes sur le chemin asynchrone — notez l'identifiant et passez à l'interrogation.

4. Essayer l'image-to-image

Ajoutez l'image source à l'objet input, en laissant le reste inchangé :

curl -sS -X POST "$HIAPI_BASE/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$FLUX_MODEL"'",
    "input": {
      "prompt": "Reinterpret as a watercolor painting, keep the composition and shadows intact",
      "image": "https://example.com/source.jpg"
    }
  }'

Comme la requête ne diffère que par un seul champ, votre premier appel réussi a déjà validé l'essentiel de l'intégration. Le reste — nouvelles tentatives, stockage, UI — relève du travail applicatif ordinaire.

La même requête en Python

L'appel curl se traduit directement. Voici un petit client réutilisable plutôt qu'un script jetable.

import os
import time
import requests

BASE = os.environ["HIAPI_BASE"]
MODEL = os.environ["FLUX_MODEL"]
HEADERS = {
    "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
    "Content-Type": "application/json",
}


def generate(prompt, image=None, timeout=60):
    """Submit a flux-3 generation job. Pass image= for image-to-image."""
    payload = {"model": MODEL, "input": {"prompt": prompt}}
    if image:
        payload["input"]["image"] = image

    resp = requests.post(
        f"{BASE}/v1/images/generations",
        headers=HEADERS,
        json=payload,
        timeout=timeout,
    )
    resp.raise_for_status()
    return resp.json()

Quelques choix délibérés :

  • Une fonction, deux modes. Le paramètre image bascule le comportement, l'appelant n'a pas à brancher.
  • Délai d'expiration explicite. Le comportement par défaut de requests — attente infinie — est précisément ce qui épuise un pool de threads de travail.
  • raise_for_status(). Faites remonter les échecs de la couche HTTP sous forme d'exceptions, que vous pouvez intercepter en un seul endroit.

Ajouter un assistant d'interrogation

Lorsque la réponse porte un identifiant de tâche plutôt qu'une image terminée, attendez-la :

def wait_for(job_id, timeout=300, initial=1.0, factor=1.6, cap=15.0):
    deadline = time.monotonic() + timeout
    delay = initial
    while time.monotonic() < deadline:
        r = requests.get(
            f"{BASE}/v1/jobs/{job_id}", headers=HEADERS, timeout=30
        )
        r.raise_for_status()
        data = r.json()
        if data.get("status") in ("succeeded", "failed"):
            return data
        time.sleep(delay)
        delay = min(delay * factor, cap)
    raise TimeoutError(f"job {job_id} did not finish in {timeout}s")

Adaptez le nom du champ de statut selon la structure de réponse documentée. La structure elle-même — backoff plafonné, échéance ferme, vérification d'état terminal — est l'essentiel, et s'applique telle quelle lorsque vous changez de modèle.

Assembler le tout

if __name__ == "__main__":
    result = generate(
        "A minimal studio photograph of a ceramic mug, soft side light"
    )
    if "id" in result and not result.get("output"):
        result = wait_for(result["id"])
    print(result)

Ensuite, enveloppez generate avec votre propre couche de nouvelles tentatives et de journalisation, et l'intégration est prête pour la production.

Maîtrise des coûts et erreurs courantes

Garder les dépenses prévisibles

La génération d'images est facturée à la requête, selon le modèle et les paramètres — consultez le panneau de tarification en temps réel dans la console plutôt que de coder des hypothèses en dur. C'est la discipline d'ingénierie qui protège le budget :

  • Fixez des limites par utilisateur et par tâche dans votre propre code. La plateforme applique des limites au niveau du compte ; votre application doit appliquer des limites au niveau produit, afin qu'un seul client incontrôlé n'épuise pas le compte.
  • Cachez agressivement. Hachez le prompt normalisé plus les paramètres, et réutilisez les sorties stockées. Les requêtes identiques sont courantes dans les scénarios d'éditeur et d'aperçu.
  • Générez à la résolution de livraison. Rendez la taille que vous allez afficher ; évitez le schéma coûteux « rendre en grand puis réduire ».
  • Placez la régénération derrière une action utilisateur explicite. La régénération automatique à chaque frappe dans le champ de prompt est le multiplicateur de coûts accidentels le plus courant.
  • Enregistrez le modèle, les paramètres et la latence de chaque appel. Sans cela, vous ne pouvez pas déterminer quelle fonctionnalité coûte cher.
  • Validez l'entrée avant la soumission. Rejetez côté client les prompts vides ou anormalement longs, afin de ne jamais payer pour des requêtes vouées à l'échec.

Déboguer les pannes que vous rencontrerez réellement

Parcourez cette liste dans l'ordre ; elle résout la plupart des incidents.

  1. 401 / 403 — authentification. La clé est-elle chargée dans l'environnement où la requête s'exécute réellement ? Une clé disponible dans votre shell peut ne pas exister dans un conteneur. Vérifiez que le préfixe Bearer et le nom d'en-tête sont exactement corrects.
  2. 404 — chemin ou modèle erroné. Les chemins versionnés et les identifiants de modèle changent. Comparez caractère par caractère avec le point de terminaison documenté.
  3. 422 / 400 — charge utile rejetée. Le corps d'erreur indiquera le champ en cause. Suspects courants : type incorrect, prompt manquant ou paramètre non pris en charge. Renvoyez en supprimant les paramètres optionnels pour isoler le problème.
  4. 429 — limitation de débit déclenchée. Reculez avec un jitter et réessayez ; ne réessayez pas immédiatement en boucle. Distinguez cela de l'épuisement du quota au niveau du compte, où réessayer ne sert à rien.
  5. Délai d'expiration. Si la requête prend trop de temps, vous bloquez là où vous devriez interroger. Passez au flux asynchrone et fixez délibérément les délais côté client.
  6. Tâche bloquée en pending. Interrogez avec une échéance et traitez l'expiration comme un échec méritant une alerte, plutôt qu'une attente infinie.

Une habitude relie toute cette liste : enregistrez le corps d'erreur complet, pas seulement le code de statut. Le corps d'erreur vous indique généralement précisément quel champ ou quelle limite pose problème, transformant une demi-heure de débogage en une correction d'une ligne.

Commencez par faire fonctionner l'appel curl, portez-le vers le client ci-dessus, centralisez l'interrogation et la gestion des erreurs en un seul endroit — le reste de l'intégration n'est que du code applicatif ordinaire. Pour les capacités actuelles du modèle et les prix, consultez la documentation flux-3 et le panneau de tarification dans la console HiAPI.

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