Tutoriel
Comment utiliser krea-3/text-to-image via l'API HiAPI : curl, Python et une requête exécutable
Sur cette page
Pourquoi appeler krea-3/text-to-image via une API agrégée
Chaque nouveau modèle d'image signifie un SDK de plus, un nouveau schéma d'authentification, un nouvel ensemble de bizarreries de réponse. Si vous ne publiez qu'une seule fonctionnalité d'image, ce coût reste tolérable. Mais si vous en publiez plusieurs — ou si vous souhaitez pouvoir changer librement de modèle plus tard — cela devient le principal coût de votre travail.
Appeler krea-3/text-to-image via HiAPI élimine ce coût. Vous intégrez une seule fois avec une convention d'endpoint unique, un seul identifiant et une seule structure de réponse. L'identifiant du modèle devient un champ du payload de la requête, et non une bifurcation dans votre base de code. Quand vous voulez comparer la sortie avec d'autres modèles d'image ou migrer une charge de travail, vous changez une chaîne de caractères, pas une intégration.
Pour ce modèle précis, les bénéfices concrets sont les suivants :
- Une structure commune à toutes les requêtes. Les appels de génération d'image suivent les mêmes conventions d'authentification et de payload sur toute la plateforme, donc ce que vous apprenez lors du premier appel se transfère directement au modèle suivant.
- Un code applicatif indépendant du modèle. Gardez le nom du modèle dans la configuration. Prototyper avec
krea-3/text-to-imagepuis passer à un autre modèle pour la mise en production ne devrait pas nécessiter de modifier votre couche HTTP. - Un point d'observation unifié de l'usage. Facturation, journaux de requêtes et réponses d'erreur proviennent de la même interface, et non de N tableaux de bord fournisseurs.
- Moins de clés. Quel que soit le nombre de modèles que vous appelez, vous ne stockez, ne faites tourner et ne restreignez qu'une seule clé.
Le prix à payer est le coût habituel de l'agrégation : vous travaillez via une interface générique, donc les bizarreries propres à chaque modèle sont normalisées. En pratique, c'est exactement ce que vous voulez — des entrées normalisées, des erreurs prévisibles et la liberté de traiter le modèle comme un paramètre réglable.
Ce tutoriel reste volontairement limité. Nous allons construire une requête exécutable, l'exécuter deux fois (d'abord avec curl, puis avec Python), observer comment la formulation du prompt oriente la sortie vers un style photographique ou illustratif, puis déboguer les quelques échecs qui représentent la majorité des problèmes au premier appel. Pas de schéma d'architecture, pas de prise de position sur un framework — juste une requête que vous pouvez envoyer dans les cinq prochaines minutes, et une checklist à utiliser en cas de problème.
Hypothèses : vous avez un compte HiAPI, vous pouvez lire la clé API depuis le tableau de bord, et vous êtes à l'aise avec un terminal et un interpréteur Python. Rien d'autre n'est nécessaire.
Avant d'envoyer la requête
Trois conditions doivent être remplies avant le premier appel. Faites-les bien, et le reste relève surtout du réglage ; faites-les mal, et vous passerez une heure à déboguer au mauvais niveau.
1. Compte et clé API
Connectez-vous à HiAPI et récupérez votre clé API depuis le tableau de bord. Traitez-la comme un secret : elle doit vivre dans une variable d'environnement ou un gestionnaire de secrets, jamais dans un fichier commité, jamais dans un prompt ou un message au support. Les exemples ci-dessous la lisent depuis une variable d'environnement :
export HIAPI_API_KEY="your-key-here"
Si votre organisation prend en charge plusieurs clés, utilisez une clé dédiée à cette intégration afin de pouvoir la faire tourner indépendamment des autres exécutions.
2. Convention d'endpoint et en-tête d'authentification
Les requêtes HiAPI utilisent l'authentification par bearer token — le même schéma que vous avez vu dans une centaine d'autres API :
Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json
Utilisez l'URL de base indiquée dans la référence API HiAPI pour la région de votre compte, et ajoutez-y le chemin de génération d'image qui y est documenté. Ne devinez pas le chemin de mémoire ou depuis un article de blog (y compris celui-ci) — la référence API est l'unique source de vérité, et le chemin est la seule partie de la requête susceptible de changer sans préavis. Conseil de tutoriel : consultez la référence une fois, copiez l'URL et conservez-la dans une valeur de configuration.
3. L'identifiant du modèle, orthographié exactement
L'identifiant du modèle est krea-3/text-to-image. Gardez le préfixe d'espace de noms et le tiret exactement tels quels — krea3/text2image ou krea-3 seul échoueront avec un modèle introuvable. La casse compte aussi. Stockez-le comme constante :
MODEL = "krea-3/text-to-image"
C'est cette chaîne qui rend votre intégration indépendante du modèle, alors nommez-la et traitez-la comme de la configuration, plutôt que de la coder en dur à chaque point d'appel.
Ce que vous n'avez pas besoin de déterminer à l'avance
Vous n'avez pas besoin de connaître avant le premier appel les noms des champs de taille d'image, de seed ou d'étapes. Commencez par le minimum : authentification, identifiant du modèle, prompt. Une fois que vous obtenez une réponse 200, ajoutez les paramètres un par un, car une requête en échec avec cinq champs configurés vous donne cinq suspects. Une requête en échec minimale ne vous en donne qu'un.
Construire une requête exécutable avec curl
curl est le moyen le plus rapide d'isoler les deux problèmes du premier appel : les identifiants et la structure du payload. Pas de version de SDK, pas d'environnement virtuel, pas de runtime asynchrone — juste une requête sur le réseau.
L'appel minimal ne porte que ce dont le modèle a réellement besoin : l'en-tête d'authentification, l'identifiant du modèle et le prompt.
curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "krea-3/text-to-image",
"prompt": "A weathered fisherman mending a net on a dock at dawn, overcast light, 35mm photograph"
}'
Deux remarques avant d'exécuter. D'abord, $HIAPI_BASE_URL est un placeholder — définissez-le avec l'URL de base de la référence API HiAPI, et vérifiez le segment de chemin dans la même référence. Ensuite, le drapeau -sS garde la sortie silencieuse tout en affichant les erreurs, ce qui est exactement ce que vous voulez en débogage.
À quoi ressemble une réponse saine : un objet JSON contenant une référence ou des données d'image générée, ainsi que les métadonnées de la requête. La structure exacte est documentée dans la référence API ; n'écrivez pas de code de parsing pour une structure que vous n'avez pas encore observée. Enregistrez la réponse réelle dans un fichier pour disposer d'une vérité de référence :
curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"krea-3/text-to-image","prompt":"A neon-lit alley after rain, cinematic still"}' \
-o response.json
Inspectez-le ensuite avec jq ou votre éditeur. Ce fichier est votre fixture de test : quand vous portez le code vers Python, comparez les sorties. Si la réponse Python diffère structurellement de response.json, le problème est dans votre code, pas dans le modèle.
La raison de commencer par curl est le levier de diagnostic. Si l'appel curl réussit, votre clé est bonne, l'URL est correcte et l'identifiant du modèle se résout — donc tout échec ultérieur vient de votre code applicatif. Si l'appel curl échoue, le corps de l'erreur vous dit lequel des trois pose problème, et vous n'avez pas encore écrit une ligne de code.
Une fois la requête minimale réussie, ajoutez un paramètre à la fois. Relancez curl après chaque ajout. Conservez les payloads qui réussissent ; ils deviendront vos fixtures d'entrées acceptées pour les tests.
La même requête en Python
La version Python reste volontairement ennuyeuse : même URL, mêmes en-têtes, même corps JSON. L'objectif est la portabilité — la structure de requête que vous avez validée avec curl doit migrer vers un script, puis vers un service, sans refonte.
import os
import json
import requests
BASE_URL = os.environ["HIAPI_BASE_URL"].rstrip("/")
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = "krea-3/text-to-image"
def generate(prompt: str) -> dict:
response = requests.post(
f"{BASE_URL}/v1/images/generations",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json={"model": MODEL, "prompt": prompt},
timeout=120,
)
response.raise_for_status()
return response.json()
if __name__ == "__main__":
result = generate(
"A weathered fisherman mending a net on a dock at dawn, overcast light, 35mm photograph"
)
print(json.dumps(result, indent=2))
Quelques choix délibérés :
- Variables d'environnement plutôt que des littéraux. La clé n'apparaît jamais dans le code source. Si la variable est absente,
os.environ["HIAPI_API_KEY"]échoue bruyamment au démarrage, ce qui vaut mieux qu'un 401 déroutant trois couches plus bas. - Appeler
raise_for_status()avant de parser. Vous voulez que les erreurs HTTP remontent sous forme d'exceptions, et non qu'unKeyErrorsurvienne lorsque vous essayez de lire un champ dans un corps d'erreur qui est justement du JSON. - Un timeout généreux. La génération d'image n'est pas un endpoint instantané. Fixez un timeout qui en tient compte et gérez-le explicitement en production (voir la section production).
- Utiliser
json=plutôt que construire une chaîne à la main. Laissez la bibliothèque sérialiser. Concaténer du JSON manuellement est justement la source des virgules finales et des erreurs de guillemets.
Exécutez-le une fois et comparez la sortie au response.json capturé précédemment. La structure doit correspondre. Affichez la référence d'image ou les données d'image décodées selon ce que renvoie la réponse — encore une fois, écrivez le code pour la structure observée, pas pour une structure supposée.
Comme MODEL est une constante, la même fonction generate() fonctionne pour n'importe quel modèle d'image de la plateforme. C'est le retour sur investissement du modèle agrégé : la déplacer dans un service, ajouter un second modèle ou faire des tests A/B sur les sorties ne sont que des changements de paramètres, pas des réécritures.
Contrôler le style photographique et le style illustration
Le style n'est pas un interrupteur ; c'est une direction dans laquelle vous poussez le modèle, et krea-3/text-to-image répond aux mêmes leviers que vous utiliseriez avec un photographe ou un illustrateur : sujet, médium, lumière et vocabulaire de métier.
Orienter vers un style photographique
La sortie photographique passe surtout par la nomination de l'instrument et de ses conséquences. Les mots qui décrivent l'appareil, l'objectif, la pellicule et une lumière réelle fonctionnent mieux que le mot « réaliste ».
- Nommez le médium et la prise de vue : « photographie 35 mm », « portrait éditorial », « still documentaire ».
- Nommez la lumière : « lumière du jour couverte », « contre-jour à l'heure dorée », « softbox unique à gauche de la caméra ».
- Nommez les imperfections : « léger flou de mouvement », « grain visible », « faible profondeur de champ ».
Comparez « un pêcheur sur un quai » avec « un pêcheur vieilli ravaudant un filet sur un quai à l'aube, lumière couverte, photographie 35 mm, grain visible ». Le second prompt contraint le modèle vers la texture et la lumière de la photographie, plutôt que vers une représentation générique.
Orienter vers un style illustration
L'illustration passe par la nomination de la tradition, de la qualité du trait et de la palette — et souvent par le retrait des indices photographiques que vous venez d'apprendre.
- Nommez le style : « illustration vectorielle plate », « encre et aquarelle », « illustration éditoriale du milieu du siècle », « line art isométrique ».
- Nommez le trait : « traits propres et uniformes », « lignes gestuelles libres ».
- Nommez la palette : « palette restreinte de deux couleurs », « pastels doux ».
Itérer plutôt que présélectionner
Traitez le prompt comme de la configuration réglable. Changez une seule dimension à la fois — remplacez uniquement la phrase de médium, en gardant le sujet et la lumière identiques — afin de comprendre le rôle de chaque terme. Tenez un court journal des variantes de prompts et des sorties qu'elles produisent ; ce journal vaut plus que n'importe quelle bibliothèque de presets, car il est calibré sur votre modèle et votre contenu.
Si la requête expose des paramètres au-delà du prompt — taille, seed ou autre — ajustez-les après avoir fixé le prompt, pas avant. Changer le prompt et trois paramètres en même temps ne vous dit pas quel changement a compté.
Diagnostiquer les erreurs courantes
La plupart des échecs au premier appel se rangent dans quatre catégories. Suivez la checklist dans l'ordre ; chaque étape élimine une couche.
Échecs d'authentification
Symptôme : 401 ou 403, avec un message sur les identifiants ou les permissions.
HIAPI_API_KEYest-elle réellement définie dans le shell qui exécute la commande ?echo $HIAPI_API_KEY— une chaîne vide ressemble beaucoup à une mauvaise clé.- L'en-tête est-il exactement
Authorization: Bearer <key>? UnBearermanquant, des guillemets superflus ou un saut de ligne collé dans la clé provoquent un échec. - La clé a-t-elle été révoquée, ou est-elle limitée à un environnement différent ? En cas de doute, régénérez-la et retestez avec un appel curl.
Payload de requête mal formé
Symptôme : 400, avec un message sur le corps, les champs ou le parsing JSON.
- Validez le JSON avant de l'envoyer. Avec curl, un guillemet non échappé dans le prompt casse le corps. Avec Python,
json=s'en charge pour vous — une raison de plus de le préférer. - Vérifiez la présence de
Content-Type: application/json. - Vérifiez les noms de champs par rapport à la référence API. Une valeur correctement orthographiée sous un mauvais nom de champ reste un 400.
- Revenez au payload minimal — modèle et prompt uniquement — confirmez qu'il fonctionne, puis ajoutez les champs un par un.
Identifiant de modèle incorrect
Symptôme : 404, ou 400 indiquant un modèle inconnu ou indisponible.
- Comparez votre chaîne caractère par caractère avec
krea-3/text-to-image. Le préfixe d'espace de noms, le tiret et le segment de chemin comptent. - Vérifiez qu'aucun espace ou guillemet typographique n'a été introduit par un copier-coller depuis la documentation.
- Confirmez que la valeur n'est pas écrasée par une valeur par défaut de configuration quelque part dans le code.
Réponses de débit et de quota
Symptôme : 429, ou un message sur une limite ou un solde insuffisant.
- Reculez et réessayez après un court délai, plutôt que de marteler l'endpoint.
- Vérifiez votre usage et votre solde dans le tableau de bord.
- Si cela arrive pendant le développement, cherchez une boucle de réessai qui se déclenche plus vite que prévu — une requête en échec dans un bloc
tryavec des réessais agressifs épuise rapidement les limites.
Si rien de tout cela ne résout le problème, capturez l'ID de requête complet et le corps d'erreur de la réponse, et envoyez-les au support. Les corps d'erreur d'une API agrégée sont généralement assez précis pour indiquer le problème ; l'erreur consiste à les paraphraser plutôt qu'à les coller.
Passer en production
Votre requête actuelle est un prototype. Quatre pratiques en font quelque chose qui peut tourner durablement.
Traiter les erreurs par catégorie, pas par chaîne
Faites correspondre les codes de statut HTTP à des comportements : les erreurs d'authentification sont un défaut de configuration qui doit alerter quelqu'un ; les erreurs 4xx de payload sont un défaut de code qui doit faire échouer la requête bruyamment ; les 429 et 5xx sont transitoires et doivent être réessayés avec un backoff exponentiel et du jitter. Ne réessayez jamais un 400 — vous ne ferez que consommer du quota pour confirmer le même défaut. Fixez des timeouts explicites et traitez les timeouts comme transitoires.
if response.status_code == 429 or response.status_code >= 500:
raise TransientError(response.status_code)
response.raise_for_status()
Journaliser les prompts et les versionner
Chaque image générée doit être traçable jusqu'au prompt exact qui l'a produite. Stockez le prompt, l'identifiant du modèle, les paramètres et l'ID de requête de la réponse ensemble. Traitez le texte du prompt comme de la configuration versionnée — une chaîne prompt_v3 commitée dans un fichier de configuration, plutôt qu'un littéral enfoui dans une fonction. Quand la qualité de sortie change, vous devez savoir si c'est le prompt, les paramètres ou le modèle qui a changé.
Garder le nom du modèle dans la configuration
krea-3/text-to-image ne doit apparaître qu'une seule fois, dans une constante ou une entrée de configuration. C'est le retour sur investissement du modèle agrégé : remplacer le modèle, lancer des comparaisons ou revenir en arrière deviennent des changements de configuration, et non le déploiement d'un nouveau chemin de code. Cela rend aussi trivial le routage de différentes charges de travail vers différents modèles.
Tester contre des fixtures
Enregistrez comme fixtures les réponses réussies capturées dans ce tutoriel. Assurez-vous que votre code de parsing les gère, et utilisez les corps d'erreur enregistrés pour tester le mapping des erreurs. Vous détecterez la dérive de structure de réponse avant vos utilisateurs.
Commencez par l'appel curl minimal, confirmez la structure de réponse, portez-la telle quelle vers Python, puis itérez sur le prompt une dimension à la fois — et consultez la référence API HiAPI pour les détails d'endpoint susceptibles d'évoluer.
Articles similaires
Voir tous les articles →-
Tutoriel
Guide pratique de gpt-6.2-sol : 5 usages à forte valeur des modèles textuels en entreprise
-
Tutoriel
Guide pratique de gpt-6.2-astra : intégration et points clés de mise en œuvre pour 5 scénarios textuels à forte valeur
Liste de points de contrôle pour les développeurs, de la sélection des scénarios à la mise en œuvre technique
-
Tutoriel
Cas d'usage concrets de Tripo H3.1 : 5 usages à forte valeur et points clés de mise en œuvre
Du texte-vers-3D à la reconstruction multi-vues : choisir le bon mode et les bons paramètres selon le cas d'usage