Comment utiliser l'API de génération d'images à partir de texte krea-2-medium-turbo (curl + Python)

krea-2-medium-turbo est le palier de génération d'images à partir de texte rapide et économique proposé par Krea sur hiapi. Il suffit d'envoyer un prompt, de choisir un rapport d'aspect, et d'obtenir une image rendue via l'API de tâches asynchrone. Ce guide fournit des exemples de requêtes curl et Python prêts à copier-coller, ciblant /v1/tasks, avec le schéma d'entrée exact, ainsi que les temps d'exécution et comportements d'erreur que j'ai mesurés en conditions réelles le 2026-10-21 — dont un résultat qui contredit la documentation.

Prérequis

Une clé API hiapi (sk-...). Créez-la dans la console API Keys. Chaque requête est authentifiée via Authorization: Bearer sk-<your-key>. C'est le seul prérequis — le modèle s'exécute côté serveur, donc rien d'autre qu'un client HTTP n'est nécessaire.

Schéma d'entrée

krea-2-medium-turbo accepte cinq champs. Seuls prompt et model sont obligatoires :

Champ	Obligatoire	Type	Valeur par défaut	Description
model	Oui	string	—	Doit être exactement krea-2-medium-turbo.
prompt	Oui	string	—	1 à 5000 caractères.
aspect_ratio	Non	enum	1:1	L'une des valeurs suivantes : 1:1, 4:3, 3:2, 16:9, 2.35:1, 4:5, 2:3, 9:16.
creativity	Non	enum	low	raw (le plus littéral) → low → medium → high (le plus créatif).
seed	Non	integer	—	Facultatif. Avant de vous y fier, lisez la mise en garde sur le seed ci-dessous.

L'objet input est strict (additionalProperties: false) : tout champ absent de ce tableau est rejeté avant le début de la génération. Pas de n / num_images, pas de resolution ni de size, et pas de champ de prompt négatif. Une requête renvoie exactement une image, et les dimensions de sortie sont entièrement déterminées par aspect_ratio. Si vous avez utilisé sur hiapi d'autres API d'images acceptant resolution (Seedream, Qwen-Image) ou size, supprimez ces champs ici — ils renverront une erreur 400.

Requête minimale fonctionnelle (curl)

La création de la tâche renvoie immédiatement un taskId ; l'image est rendue en arrière-plan.

curl -s -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "krea-2-medium-turbo",
    "input": {
      "prompt": "A lighthouse on a rocky coast at golden hour, cinematic wide shot",
      "aspect_ratio": "2.35:1",
      "creativity": "medium",
      "seed": 42
    }
  }'

Réponse :

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

Interrogez ensuite la tâche par son id jusqu'à atteindre un état terminal :

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

Une tâche terminée se présente ainsi (champs tronqués pour plus de clarté) :

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M5E4J4FQVJNSDKQ29BRSMD0A",
    "model": "krea-2-medium-turbo",
    "status": "success",
    "storage": "temp",
    "created": 1792549655,
    "completed": 1792549681,
    "output": [
      {
        "type": "image",
        "url": "https://temp.hiapi.ai/xxxxxxxx/01M5E4J4FQVJNSDKQ29BRSMD0A-0.png",
        "artifactId": "280334",
        "expireAt": 1793154481
      }
    ]
  },
  "message": "success"
}

L'image se trouve dans data.output[0].url.

Le même flux en Python

import time
import requests

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

def generate(prompt, aspect_ratio="1:1", creativity="low", seed=None):
    body = {
        "model": "krea-2-medium-turbo",
        "input": {"prompt": prompt, "aspect_ratio": aspect_ratio, "creativity": creativity},
    }
    if seed is not None:
        body["input"]["seed"] = seed

    created = requests.post(API, headers=HEADERS, json=body, timeout=30)
    created.raise_for_status()
    task_id = created.json()["data"]["taskId"]

    # Interroger jusqu'à ce que la tâche atteigne un état terminal.
    while True:
        data = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        status = data["status"]
        if status == "success":
            return data["output"][0]["url"]
        if status == "fail":                 # Attention : toujours HTTP 200, voir ci-dessous
            raise RuntimeError(f"generation failed: {data}")
        time.sleep(3)

url = generate(
    "A lighthouse on a rocky coast at golden hour, cinematic wide shot",
    aspect_ratio="2.35:1",
    creativity="medium",
)
print(url)

Points d'attention pour la production

• Interrogation ou callback. La boucle ci-dessus interroge toutes les 3 secondes, ce qui convient à un faible volume de requêtes simultanées. En production, vous pouvez joindre callback.url avec when: "final" lors de la requête de création, pour que hiapi vous envoie la tâche terminée par POST au lieu de l'interroger — la convention de callback est décrite dans la documentation de l'API de tâches.
• Un échec de génération renvoie quand même HTTP 200. Le code de statut HTTP sur l'endpoint d'interrogation indique si la requête a réussi, et non si l'image a réussi. Un échec de rendu est renvoyé avec 200 et data.status: "fail". Branchez sur data.status, et non sur le code de statut HTTP, sinon vous traiterez un échec comme un succès.
• Les URL de sortie sont temporaires. Les résultats sont stockés sous "storage": "temp" sur temp.hiapi.ai, avec un horodatage expireAt, et expirent au bout d'environ sept jours (604 800 secondes lors de mes tests). Téléchargez les octets et réhébergez-les (votre propre bucket/CDN) dès que la tâche est terminée — ne créez pas de lien direct vers les URL temp.hiapi.ai dans vos pages de production.
• La tarification est un tarif fixe unique par image, indépendamment du rapport d'aspect ou du niveau de créativité — aucun palier de résolution à prendre en compte. Consultez les chiffres actuels sur la page de tarification plutôt que de les coder en dur.

Ce que j'ai réellement testé (2026-10-21)

Tout ce qui suit provient d'appels réels, et non de la documentation :

• Temps d'exécution et résolution. Une requête 2.35:1 s'est terminée en environ 26 secondes (différence created → completed), et le PNG renvoyé faisait 1568 × 672 px — donc 2.35:1 est bien un recadrage cinémascope, et non un format quasi carré. La tâche passe par les états intermédiaires handling → archiving → success pendant le rendu et le déplacement du fichier vers le stockage temporaire.
• La validation des énumérations est appliquée côté serveur. Envoyer "aspect_ratio": "21:9" (une valeur plausible mais non prise en charge) renvoie immédiatement 400 : invalid input: aspect_ratio: value must be one of '1:1', '4:3', '3:2', '16:9', '2.35:1', '4:5', '2:3', '9:16'. Le message d'erreur indique le champ et énumère les valeurs valides, ce qui facilite le traitement programmatique.
• Les champs inconnus renvoient 400, ils ne sont pas ignorés. "resolution": "2K" renvoie invalid input: <root>: additional properties 'resolution' not allowed ; "n": 2 renvoie la même erreur pour n. C'est la règle additionalProperties: false à l'œuvre — si vous copiez un corps de requête depuis un autre modèle, les champs superflus bloquent tout l'appel.
• Dans mon test, seed n'a pas permis de reproduire une image identique. J'ai envoyé deux fois de suite le même prompt, seed: 42, aspect_ratio: 2.35:1 et creativity: medium. Les deux fois, une image valide de 1568 × 672 a été renvoyée, mais clairement une scène différente (une tour blanche dans un cas, une tour à rayures rouges et blanches dans l'autre), avec des tailles de fichier différentes (1,30 Mo contre 1,51 Mo) et des hachages différents. Le champ est accepté et décrit comme reproductible dans la documentation, mais considérez la reproduction exacte au pixel près comme un meilleur effort et non une garantie — si vous avez besoin d'une image précise, enregistrez le résultat obtenu au lieu de le redemander avec un seed.

Pages associées

• Page du modèle krea-2-medium-turbo — playground en ligne et référence complète des paramètres.
• Documentation de l'API krea-2-medium-turbo — détails sur l'endpoint et les callbacks.
• Krea 3 texte-vers-image — le palier Krea plus récent axé sur la qualité (avec les modes berry/jam) ; utilisez-le lorsque vous voulez plus de finesse, et krea-2-medium-turbo lorsque vous voulez rapidité et coût réduit.
• API de génération d'images IA sur hiapi — les autres modèles texte-vers-image derrière la même interface de tâches.

FAQ

Quels rapports d'aspect puis-je demander ? Huit : 1:1 (par défaut), 4:3, 3:2, 16:9, 2.35:1, 4:5, 2:3 et 9:16. Toute autre valeur renvoie 400.

Un appel peut-il générer plusieurs images ? Non. Il n'y a pas de champ n, et le schéma rejette les propriétés inconnues, donc chaque requête génère exactement une image. Pour générer en lot, envoyez les requêtes en boucle (éventuellement avec des seeds différents).

À quoi sert creativity ? Il contrôle le degré de littéralité avec lequel le modèle suit le prompt : raw est le plus fidèle à la formulation, high prend le plus de libertés d'interprétation, et low (par défaut) et medium se situent entre les deux.

krea-2-medium-turbo prend-il en charge l'image-vers-image ou l'édition ? Non — il ne prend en charge que la génération d'images à partir de texte. Le schéma ne comporte pas de champ image_urls / d'image d'entrée. Si vous devez transformer une image existante, utilisez un modèle d'édition/image-vers-image dédié sur hiapi.

Combien de temps les URL de sortie restent-elles valides ? Elles sont servies par le stockage temporaire et expirent (environ sept jours dans mes tests). Téléchargez et réhébergez les images dès que la tâche est terminée.