Tutoriel

API flux-2-klein-9b : guide curl et Python

Aug 25, 2026

Modèle: flux-2-klein-9b

Générer une image avec flux-2-klein-9b sur hiapi ne nécessite qu'un seul appel POST /v1/tasks suivi d'une interrogation périodique (polling) — exactement le même schéma de tâches asynchrones que celui utilisé par tous les modèles de la plateforme. Ce guide documente une requête et une réponse réelles (création de la tâche, polling, puis URL finale de l'image), de sorte que le code ci-dessous peut être copié et exécuté tel quel, et non simplement illustratif.

Ce dont vous avez besoin

Une clé API hiapi — à créer dans la console. Elle est envoyée sous forme de jeton Bearer à chaque requête.
L'ID de modèle complet, suffixe d'endpoint inclus. flux-2-klein-9b n'est accessible que via flux-2-klein-9b/text-to-image — indiquer uniquement flux-2-klein-9b renvoie une erreur 400 (voir ci-dessous).

Requête minimale fonctionnelle (curl)

Créer la tâche :

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2-klein-9b/text-to-image",
    "input": {
      "prompt": "a weathered lighthouse on a rocky coast at sunset, cinematic lighting",
      "aspect_ratio": "16:9"
    }
  }'

Réponse :

{"code":200,"data":{"taskId":"tk-hiapi-01M0T23CG2GNPENYQV4WEKZJTM"},"message":"success"}

Interroger la tâche jusqu'à son achèvement :

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-01M0T23CG2GNPENYQV4WEKZJTM \
  -H "Authorization: Bearer sk-<your-key>"

Réponse une fois terminée :

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M0T23CG2GNPENYQV4WEKZJTM",
    "status": "success",
    "model": "flux-2-klein-9b/text-to-image",
    "created": 1787581018,
    "completed": 1787581030,
    "storage": "temp",
    "output": [
      {
        "type": "image",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M0T23CG2GNPENYQV4WEKZJTM-0.png",
        "artifactId": "96193",
        "expireAt": 1788185830
      }
    ]
  },
  "message": "success"
}

output[0].url correspond au fichier PNG. Lors de nos tests, la tâche est passée de la soumission à success en environ 12 secondes. Notez expireAt — avant de concevoir une fonctionnalité dépendant de la disponibilité continue de cette URL, lisez les remarques sur le stockage ci-dessous.

Le même flux en Python

import time
import requests

API_KEY = "sk-<your-key>"
BASE_URL = "https://api.hiapi.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


def create_image(prompt: str, aspect_ratio: str = "1:1") -> str:
    resp = requests.post(
        f"{BASE_URL}/tasks",
        headers=HEADERS,
        json={
            "model": "flux-2-klein-9b/text-to-image",
            "input": {"prompt": prompt, "aspect_ratio": aspect_ratio},
        },
        timeout=30,
    )
    body = resp.json()
    if resp.status_code != 200 or "error" in body:
        raise RuntimeError(f"create failed: {body}")
    return body["data"]["taskId"]


def wait_for_image(task_id: str, timeout_s: int = 120, interval_s: int = 3) -> str:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE_URL}/tasks/{task_id}", headers=HEADERS, timeout=30)
        data = resp.json()["data"]
        if data["status"] == "success":
            return data["output"][0]["url"]
        if data["status"] == "failed":
            raise RuntimeError(f"task {task_id} failed: {data}")
        time.sleep(interval_s)
    raise TimeoutError(f"task {task_id} still running after {timeout_s}s")


if __name__ == "__main__":
    task_id = create_image("a weathered lighthouse on a rocky coast at sunset, cinematic lighting", "16:9")
    image_url = wait_for_image(task_id)
    image_bytes = requests.get(image_url, timeout=60).content
    with open("output.png", "wb") as f:
        f.write(image_bytes)
    print(f"saved output.png from task {task_id}")

Les paramètres réellement validés par flux-2-klein-9b

Le schéma d'entrée est très strict — si un champ non listé est envoyé, l'API rejette purement et simplement l'ensemble de la requête avant qu'elle n'entre en file d'attente :

prompt (chaîne, obligatoire) — le seul champ obligatoire.
aspect_ratio (chaîne, facultatif) — l'une des valeurs 1:1, 4:3, 3:4, 16:9, 9:16. Toute autre valeur renvoie une erreur 400 accompagnée de value must be one of ....
seed (entier, facultatif) — en transmettant la même seed avec le même prompt, on obtient des résultats reproductibles.
output_format (chaîne, facultatif) — l'une des valeurs jpeg, png, webp.

C'est tout le schéma. Il n'existe pas de champ size, quality, strength ni n — envoyer l'un d'eux échoue :

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

flux-2-klein-9b ne prend en charge que la génération d'image à partir de texte. Il n'accepte pas non plus image_urls — pour l'image à image, utilisez plutôt l'ID de modèle distinct flux-2-klein-9b/image-to-image, qui accepte une structure d'entrée différente.

L'ID de modèle doit inclure le suffixe d'endpoint

Sur hiapi, certains modèles peuvent être résolus avec un ID nu (comme gpt-image-2), mais flux-2-klein-9b n'en fait pas partie. Si vous retirez le suffixe, la tâche ne sera jamais créée :

{"code":400,"data":null,"error_code":"MODEL_UNAVAILABLE","message":"model not available via /v1/tasks"}

Envoyez toujours la chaîne complète flux-2-klein-9b/text-to-image comme model.

Points d'attention pour la production

Deux structures d'erreur différentes. Les erreurs de validation (champ manquant, valeur d'énumération incorrecte, clé inconnue) sont renvoyées sous la forme d'un objet de premier niveau {"code":400,"error_code":"INVALID_REQUEST","message":"..."}. Les erreurs d'authentification/permission sont renvoyées sous la forme {"error":{"code":"permission_denied","message":"...","request_id":"..."}} — c'est-à-dire un objet error imbriqué, avec un HTTP 401. Votre gestion des erreurs doit vérifier les deux structures ; un code qui ne teste que resp["code"] manquera les cas 401.
permission_denied désigne la clé, pas la requête. Si prompt est présent et du bon type mais que vous recevez quand même un 401 permission_denied, cela signifie que cette clé API elle-même n'a pas ce modèle activé — vérifiez-le dans la console, plutôt que de revérifier votre JSON encore et encore.
Le stockage des sorties est temporaire. storage: "temp", et chaque sortie porte un horodatage unix expireAt — environ une semaine après la création dans l'exemple capturé. Téléchargez le fichier immédiatement après le succès de la tâche ou poussez-le vers votre propre stockage ; ne conservez pas les URL temp.hiapi.ai comme adresses permanentes.
Pour les tâches en lot, utilisez un callback. Interroger une image ne pose pas de problème ; interroger cinquante images, c'est cinquante allers-retours répétés. Définissez callback: {"url": "...", "when": "final"} au niveau supérieur de la requête de création, pour que hiapi vous pousse le résultat une seule fois, au moment où la tâche se termine réellement. Actuellement, when n'accepte que la valeur "final".
Réessayez avant d'obtenir le taskId, pas après. Une erreur réseau ou un 5xx lors du POST /v1/tasks initial peut être réessayé sans risque — rien n'a encore été créé à ce stade. Une fois le taskId obtenu, resoumettre le même prompt crée une seconde image sans rapport ; dans ce cas, interrogez la tâche ou attendez le callback.

Contenu associé

Page du modèle flux-2-klein-9b — tarification actuelle et espace de démonstration en ligne.
Référence de documentation flux-2-klein-9b — l'entrée de référence propre à ce modèle.
Tarification hiapi — les tarifs de chaque modèle du catalogue.
Documentation de l'API de tâches asynchrones — la convention complète de création/polling partagée par tous les modèles hiapi.

Questions fréquentes

Pourquoi obtient-on MODEL_UNAVAILABLE lors d'un appel à flux-2-klein-9b ? L'ID de modèle doit inclure le suffixe d'endpoint. Utilisez flux-2-klein-9b/text-to-image, et non le simple flux-2-klein-9b.

Quels formats d'image flux-2-klein-9b prend-il en charge ? Cinq : 1:1, 4:3, 3:4, 16:9, 9:16. Toute autre valeur renvoie une erreur 400 avec un message value must be one of énumérant ces cinq valeurs.

Puis-je contrôler la qualité ou la résolution de la sortie ? Non — le schéma n'accepte que prompt, aspect_ratio, seed et output_format. Il n'y a pas de paramètre size ni quality ; envoyer l'un d'eux renvoie une erreur 400 additional properties.

Puis-je faire de l'édition image à image avec flux-2-klein-9b ? Pas avec cet ID de modèle. Utilisez plutôt flux-2-klein-9b/image-to-image, qui possède son propre schéma d'entrée distinct.

Quelle est la durée de validité de l'URL de sortie ? storage vaut "temp", et chaque sortie porte un horodatage unix expireAt, soit en pratique environ une semaine. Téléchargez ou téléversez à nouveau le fichier immédiatement après le succès de la tâche — ne traitez pas l'URL comme une adresse permanente.

Pourquoi une clé qui fonctionne sur d'autres modèles renvoie-t-elle un 401 sur ce modèle ? L'accès aux modèles est accordé clé par clé. Un 401 avec error_code: "permission_denied" signifie que cette clé spécifique n'est pas encore autorisée pour flux-2-klein-9b — activez-la dans la console ; ce n'est pas un bug dans le corps de votre requête.