Comment utiliser recraft-v4.1/text-to-image via l'API HiAPI : guide curl et Python

Ce que ce point de terminaison vous apporte

recraft-v4.1/text-to-image est un point de terminaison de modèle de génération d'images à partir de texte : vous envoyez un prompt textuel ainsi que plusieurs options de mise en forme dans le corps de la requête, puis vous recevez les données de l'image générée. Il est particulièrement adapté lorsque vous souhaitez produire une image finie en un seul appel, sans avoir à orchestrer vous-même un pipeline multi-étapes.

Sur HiAPI, ce modèle s'inscrit dans un mode agrégé : une URL de base, un en-tête d'authentification et une structure de requête/réponse cohérente d'un point de terminaison à l'autre. Vous n'avez pas besoin de brancher un SDK et un jeu d'identifiants distincts pour chaque modèle d'image à évaluer : pointez simplement votre client vers le point de terminaison recraft-v4.1/text-to-image sur HiAPI, et le reste du code reste stable. C'est particulièrement important lors du prototypage — vous voulez comparer des prompts, des styles et des modèles sans réécrire la couche de transport à chaque fois.

Une manière pratique de comprendre cet appel :

• Prompt — la description en langage naturel de l'image que vous souhaitez.
• Style — champ du corps de requête qui oriente le traitement visuel de la sortie.
• Resolution — champ du corps de requête qui détermine la taille de la sortie.

Comme les trois circulent dans le même corps JSON, l'ingénierie du prompt et la mise en forme de la sortie s'effectuent en un seul aller-retour. Si vous vous demandez si c'est le bon point de terminaison, la réponse est généralement oui — lorsque vous avez besoin d'une génération d'images synchrone pilotée par prompt et que vous souhaitez garder les détails de la plomberie du fournisseur hors du code applicatif.

Prérequis et authentification

Avant le premier appel, assurez-vous de disposer de :

• Un compte HiAPI et une clé API. Gardez-la hors du contrôle de source et chargez-la depuis une variable d'environnement.
• curl pour un test de fumée rapide, et Python 3 avec requests installé (si vous prévoyez d'utiliser les exemples Python).
• Un prompt que vous souhaitez réellement rendre — même approximatif, il suffit pour vérifier que le câblage est correct.

L'authentification de HiAPI repose sur les en-têtes. La clé API est transmise via un en-tête, et le même schéma d'en-tête s'applique que vous appeliez depuis curl, Python ou un autre client HTTP. La sélection du modèle s'effectue via le chemin du point de terminaison, de sorte que l'en-tête d'authentification reste inchangé lorsque vous changez de modèle.

Une configuration locale sûre ressemble à ceci :

export HIAPI_API_KEY="your-key-here"

Ensuite, référencez $HIAPI_API_KEY dans les commandes shell et os.environ["HIAPI_API_KEY"] en Python. Ne codez jamais en dur la clé dans un script susceptible d'être commité, et évitez de la coller dans des journaux ou des rapports d'erreur. Si la clé fuit, faites-la tourner dans les paramètres de votre compte plutôt que d'essayer de la purger de l'historique.

Les exemples suivants supposent deux choses : l'URL de base de l'API HiAPI et le chemin du modèle recraft-v4.1/text-to-image. Avant de brancher cela dans une construction, vérifiez ces deux éléments dans la référence API de votre compte, car l'hôte et le chemin exacts sont les seuls éléments de ce guide qui doivent être copiés depuis la documentation actuelle plutôt que de mémoire.

Une requête curl exécutable

Le moyen le plus rapide de confirmer que la clé, le point de terminaison et la structure de la charge utile fonctionnent est un appel curl. Cette requête envoie un corps JSON contenant le prompt et les champs de mise en forme, et transmet la clé API dans l'en-tête :

curl -X POST "$HIAPI_BASE_URL/recraft-v4.1/text-to-image" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A minimalist isometric illustration of a developer workstation, soft pastel palette, clean background",
    "style": "illustration",
    "resolution": "1024x1024"
  }'

Quelques points à noter concernant cet appel :

• Le chemin du point de terminaison. Le nom du modèle figure dans le chemin. Passer plus tard à un autre modèle implique de modifier ce segment de chemin, et non de reconstruire la requête.
• Corps de requête, pas chaîne de requête. prompt, style et resolution vont tous dans le corps JSON. Ainsi l'URL reste stable et la charge utile est facile à journaliser et à rejouer.
• Authentification par en-tête. L'en-tête Authorization porte la clé ; Content-Type doit être application/json.

Si vous recevez une réponse non-200 dès la première tentative, vérifiez dans cet ordre : si la clé est bien définie dans le shell, si l'URL de base n'a pas de barre oblique finale en double, et si le corps JSON est valide (les virgules finales sont souvent les coupables). Une fois l'appel réussi, enregistrez la commande exacte dans un fichier de brouillon — un appel curl connu pour fonctionner est votre référence pour comparer chaque modification de SDK et de client.

La même requête en Python

Pour du code réel, encapsulez l'appel dans une petite fonction afin que les tentatives, la journalisation et le changement de modèle aient un emplacement unique. Utilisez requests :

import os
import requests

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


def generate_image(prompt, style="illustration", resolution="1024x1024", timeout=120):
    url = f"{HIAPI_BASE_URL}/recraft-v4.1/text-to-image"
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    }
    payload = {
        "prompt": prompt,
        "style": style,
        "resolution": resolution,
    }
    response = requests.post(url, headers=headers, json=payload, timeout=timeout)
    response.raise_for_status()
    return response.json()

Points de conception à retenir :

• Utilisez json= et non data=. Passer un dict à json= définit le type de contenu pour vous et sérialise le corps, de sorte que la charge utile est identique octet pour octet à la version curl.
• Délai d'attente explicite. La génération d'images n'est pas instantanée ; un délai généreux évite de signaler à tort un échec pour une requête lente mais saine. Ne vous fiez pas aux valeurs par défaut du client.
• raise_for_status() d'abord. Convertissez les erreurs HTTP en exceptions avant de tenter de lire le corps de la réponse, afin qu'un 4xx ou 5xx ne soit jamais confondu avec des données d'image.
• Configuration pilotée par l'environnement. L'URL de base et la clé proviennent toutes deux de l'environnement, ce qui rend la fonction portable entre local, préproduction et production.

La fonction renvoie le JSON analysé. La manière d'extraire l'image de ce JSON est le sujet suivant, et c'est là que la plupart des intégrations se trompent.

Traiter la réponse d'image synchrone

recraft-v4.1/text-to-image renvoie les données d'image de manière synchrone : l'image revient dans la même réponse HTTP que la requête, sans boucle de polling ni identifiant de tâche à suivre. Cela simplifie le client, mais transfère deux responsabilités à votre code — le décodage de la charge utile et la gestion explicite des échecs.

Le chemin de traitement robuste est le suivant :

1. Vérifiez le statut avant d'analyser. Traitez tout non-200 comme une erreur et affichez le corps de la réponse, qui explique souvent le problème.
2. Lisez le champ d'image avec intention. Le JSON de réponse porte les données d'image ; selon le champ reçu, il peut s'agir d'une URL ou d'octets d'image encodés. Gérez les deux chemins plutôt que d'en supposer un.
3. Décodez défensivement. Si la charge utile est encodée en base64, décodez-la et écrivez les octets dans un fichier. Ne faites pas passer de données binaires par un chemin réservé au texte et ne les imprimez pas dans le terminal.
4. Limitez la taille de la charge utile. Les réponses d'image synchrones sont volumineuses comparées à un JSON typique. Écrivez en flux sur le disque lorsque le client le permet, et évitez de garder plusieurs réponses en mémoire simultanément.

Étape minimale d'enregistrement pour une charge utile base64 :

import base64

data = generate_image("A calm forest at dawn, soft light")
image_b64 = data["image"]  # adjust to the actual field name in the response
with open("out.png", "wb") as f:
    f.write(base64.b64decode(image_b64))

Deux modes d'échec méritent un traitement dédié. Les délais d'attente doivent être réessayés avec un backoff, mais uniquement dans l'hypothèse d'idempotence — régénérer une image produit un résultat différent, donc journalisez le prompt à chaque tentative. Les erreurs client (comme un corps de requête mal formé ou une valeur d'option invalide) ne se corrigeront pas par une nouvelle tentative ; échouez rapidement et journalisez le texte de la réponse. Enfin, vérifiez la présence du champ d'image avant de décoder, afin qu'un changement de schéma ou une charge utile erronée déclenche une exception claire plutôt qu'une erreur de décodage déroutante.

Adapter le style et la résolution à votre cas d'usage

style et resolution sont les deux champs du corps de requête qui influencent le plus le résultat renvoyé, et les deux sont peu coûteux à itérer car ils sont transmis avec le prompt.

Style

style oriente le traitement visuel de la sortie. Utilisez-le pour maintenir la cohérence d'une série d'images — par exemple, fixez un même style sur un lot d'illustrations produit ou d'images d'en-tête d'articles pour qu'elles forment un ensemble. Lorsque le résultat semble incorrect, vérifiez d'abord si le style correspond au contenu : appliquer un style orienté illustration à un prompt réaliste créera un conflit avec le texte. Avant d'ajouter des détails, essayez des prompts simples avec un style fixe, afin de pouvoir déterminer si un mauvais résultat provient du style ou de la formulation.

Resolution

resolution détermine la taille de la sortie. Faites-la correspondre à l'usage cible : choisissez des dimensions proches du carré pour les avatars et les vignettes, et des dimensions plus larges pour les bannières et les images principales. Deux règles pratiques :

• Ne demandez pas pour agrandir ensuite. Générez directement des images proches de leur taille d'affichage finale plutôt que de générer des petites images puis de les agrandir.
• Faites attention au rapport d'aspect. Si votre mise en page attend un ratio spécifique, choisissez une résolution correspondant à ce ratio plutôt que de recadrer après coup.

Déboguer les sorties inattendues

Lorsque l'image semble incorrecte, isolez une seule variable à la fois. Gardez le prompt inchangé et modifiez style ; puis gardez les deux inchangés et modifiez resolution. Si rien n'aide, réécrivez le prompt avec des noms concrets et des indications de composition explicites plutôt qu'en ajoutant des adjectifs. Vérifiez également que vous n'envoyez pas discrètement un mauvais type de valeur — une chaîne de style ne correspondant pas aux options acceptées peut être rejetée ou ignorée selon la logique de validation. Journalisez le corps exact de chaque appel ; c'est la seule trace fiable de ce qui a produit une image donnée.

Encapsuler pour la production

La valeur de cette petite fonction apparaît lorsque vous la renforcez. Une encapsulation de niveau production doit faire quatre choses :

• Encapsuler le transport. Une fonction possède l'URL, les en-têtes, la structure de la charge utile et le délai d'attente. Les appelants ne transmettent que le prompt et les options, rien d'autre.
• Ajouter des tentatives avec backoff. Réessayez un nombre limité de fois les délais d'attente et les réponses 5xx ; ne réessayez jamais les erreurs 4xx. Comme la génération d'images n'est pas idempotente, fixez une limite basse et associez le prompt à chaque tentative.
• Journaliser la requête, pas seulement le résultat. Enregistrez le prompt, le style, la résolution, le statut et la durée. Quand quelqu'un demande pourquoi l'image ressemble à cela, ce journal est la réponse.
• Passer le modèle en paramètre. Transmettez le chemin du modèle en paramètre, avec recraft-v4.1/text-to-image par défaut. Ainsi, passer à un autre modèle d'image devient un changement de configuration plutôt qu'une refonte, ce qui rend l'évaluation côte à côte peu coûteuse.

Gardez la couche d'encapsulation légère. Résistez à l'envie d'y ajouter de la mise en cache, de la file d'attente ou des politiques de stockage — cela relève de la couche supérieure, afin qu'elles puissent évoluer indépendamment de l'appel API. Une interface stable signifie aussi que vos tests peuvent simuler la couche de transport et vérifier la charge utile que vous enverrez, ce qui détecte la plupart des erreurs d'intégration avant qu'elles n'atteignent une requête réelle.

Avec l'authentification, une requête connue pour fonctionner et un traitement explicite des réponses, vous disposez de tout le nécessaire pour appeler recraft-v4.1/text-to-image depuis HiAPI en curl et en Python, et pour changer de modèle ensuite sans toucher au reste du code.