Tutoriel
Comment utiliser seedream-4.5/text-to-image via l'API HiAPI : exemples curl et Python
Un guide pratique pour une intégration minimale exécutable destinée aux développeurs
Sur cette page
Ce que seedream-4.5/text-to-image vous apporte
seedream-4.5/text-to-image est un point de terminaison de génération d'images à partir de texte fourni par l'API HiAPI. Vous envoyez un prompt textuel et quelques paramètres optionnels, et le modèle renvoie une image générée. Vous pouvez l'utiliser pour créer des illustrations de scènes, des visuels de produits, de l'art conceptuel, ou tout contenu visuel nécessitant du texte lisible rendu dans l'image — enseignes, étiquettes, titres courts. Ce point de terminaison est sans état : chaque requête est une génération indépendante, le contrôle des répétitions et des variations relève donc de votre code applicatif.
Comme il s'exécute derrière la même interface unifiée que les autres modèles HiAPI, vous ne vous authentifiez qu'une seule fois, vous utilisez la même URL de base et les mêmes conventions d'erreur, et vous n'avez pas à apprendre un nouveau mode d'intégration lorsque vous changez de modèle. La page de détails du modèle seedream-4.5/text-to-image liste les noms de paramètres et les valeurs acceptées actuels — considérez cette page comme la source de référence pour les champs, et non cet article.
Structure de la requête : ce que vous envoyez et recevez
Chaque appel de génération d'images à partir de texte suit la même structure : une requête POST avec un corps JSON envoyée au point de terminaison HiAPI du modèle. Le corps contient les champs requis par le modèle ; la réponse contient l'image générée et des métadonnées sur la requête.
Ce que vous envoyez
prompt(chaîne, obligatoire) : la description de l'image. C'est le principal levier de contrôle ; voir la section sur les prompts ci-dessous.aspect_ratioou un champ lié aux dimensions (facultatif) : contrôle la forme du canevas de sortie. Utilisez le nom de champ exact indiqué sur la page du modèle — ne partez pas du principe qu'il est identique à celui d'autres modèles.- Toute option propre au modèle documentée sur sa page (par exemple des indications de style ou de qualité). Omettez les champs dont vous n'avez pas besoin ; l'API appliquera les valeurs par défaut.
Ce que vous recevez
Une réponse réussie est un objet JSON. Les champs que votre code lira réellement sont généralement :
- La charge utile de l'image : selon le schéma de réponse, il peut s'agir de l'URL de l'image générée ou d'une chaîne d'image encodée en base64. Votre code doit gérer la forme réellement renvoyée par le point de terminaison ; la page du modèle précise laquelle.
- Les métadonnées de la requête, comme un identifiant ou un statut, utiles pour la journalisation et le support.
Tous les champs ne sont pas garantis dans toutes les versions ; validez donc la structure de la réponse plutôt que de supposer un schéma fixe. Si vous construisez un analyseur qui ne recherche que les champs dont vous avez besoin et traite les autres comme facultatifs, votre intégration résistera aux légères variations de réponse.
Votre première requête curl exécutable
L'appel valide minimal n'envoie qu'un prompt, rien d'autre. Remplacez la clé et le prompt d'exemple par les vôtres, puis exécutez-le.
curl -X POST "https://api.hiapi.ai/v1/models/seedream-4.5/text-to-image" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "un café de rue calme au crépuscule, lumière chaude aux fenêtres, un panneau en ardoise portant la mention OPEN",
"aspect_ratio": "1:1"
}'
Explication ligne par ligne :
- L'URL pointe vers le point de terminaison HiAPI de ce modèle. Conservez l'identifiant du modèle exactement tel que documenté.
- L'en-tête
Authorizationporte votre clé API. L'utilisation d'une variable d'environnement évite que la clé n'apparaisse dans l'historique de votre shell et dans vos fichiers sources. Content-Type: application/jsonindique au serveur d'analyser le corps comme du JSON.- Le corps JSON contient le prompt et un ratio d'aspect facultatif. Commencez par une image et un prompt ; itérez sur la formulation avant d'ajouter des options.
Si l'appel réussit, la réponse contient les données d'image décrites dans la section précédente. Enregistrez la sortie dans un fichier (ou ouvrez l'URL renvoyée) et inspectez-la avant d'aller plus loin. En cas d'erreur d'authentification, vérifiez que la clé existe et que l'en-tête est correctement orthographié ; en cas d'erreur de paramètre, revérifiez les noms de champs sur la page du modèle.
La même requête en Python
La version Python utilise la bibliothèque standard requests — aucun SDK n'est nécessaire.
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
URL = "https://api.hiapi.ai/v1/models/seedream-4.5/text-to-image"
payload = {
"prompt": "un café de rue calme au crépuscule, lumière chaude aux fenêtres, un panneau en ardoise portant la mention OPEN",
"aspect_ratio": "1:1",
}
response = requests.post(
URL,
headers={"Authorization": f"Bearer {API_KEY}"},
json=payload,
timeout=60,
)
response.raise_for_status()
result = response.json()
print(result)
Deux détails comptent ici. Premièrement, passez json=payload plutôt qu'une chaîne construite à la main — requests définira le type de contenu et effectuera la sérialisation correctement. Deuxièmement, définissez un timeout explicite. La génération d'images peut prendre plus de temps qu'un appel d'API typique, un délai d'attente généreux avec un mode d'échec clair est donc préférable à une requête qui reste bloquée.
Le résultat affiché est la réponse brute. Dans du code réel, extrayez le champ d'image renvoyé par votre point de terminaison (URL ou base64), puis soit téléchargez cette URL avec une seconde requête, soit décodez le base64 en octets et écrivez-les sur le disque. Placez cette logique d'extraction dans une petite fonction utilitaire afin que les tests et le code de production partagent la même logique d'analyse.
Rédiger des prompts pour le photoréalisme et un texte lisible
La qualité du prompt détermine la qualité de la sortie plus que tout autre paramètre. Les deux objectifs les plus fréquents sont : des scènes photoréalistes et du texte clairement lisible dans l'image.
Photoréalisme
Décrivez la scène comme un photographe composerait son cadre : sujet, lumière, moment de la journée, sensation d'objectif et environnement. Les noms concrets valent mieux que les adjectifs abstraits. N'écrivez pas « un joli café », mais « un intérieur de café étroit et long, lumière de midi traversant de grandes fenêtres, comptoir en bois, faible profondeur de champ ». Ajoutez une brève indication de style, comme « photograph » ou « documentary photo », pour éloigner le modèle du style illustration. Gardez un sujet principal par prompt ; des sujets concurrents produisent souvent des compositions confuses.
Texte lisible
Lorsque l'image doit contenir du texte, placez le texte exact entre guillemets et gardez-le court. Un panneau portant OPEN ou une étiquette indiquant FRESH BREAD sera bien plus fiable qu'un paragraphe entier. Précisez où le texte apparaît — « un panneau en ardoise portant OPEN au-dessus du comptoir » — pour que le modèle sache que ce texte appartient à un objet. Si le texte est brouillé, raccourcissez-le, simplifiez la scène autour et régénérez. De légers ajustements de formulation sont normaux ; prévoyez plusieurs itérations.
Itération
Ne changez qu'une variable à la fois : d'abord le prompt, puis le ratio d'aspect, enfin les éventuelles options de style. Conservez vos prompts ainsi que les réglages qui ont produit de bons résultats. Cette trace deviendra votre référence de régénération et évitera que le débogage ne se transforme en devinettes.
Choisir le ratio d'aspect et les réglages de sortie
Le ratio d'aspect détermine la composition avant même que le modèle ne dessine quoi que ce soit. Choisissez-le en fonction de l'usage visé, et non pour correspondre à une valeur par défaut.
- Carré (
1:1) : publications sociales, avatars, vignettes produits. Simple et sûr. - Paysage (par exemple
16:9) : bannières, visuels principaux, diapositives de présentation. Favorise les scènes larges — lignes d'horizon, façades de magasins, intérieurs spacieux. - Portrait (par exemple
9:16) : écrans mobiles, stories, affiches. Les prompts avec un sujet vertical net — une personne debout, un bâtiment élancé — fonctionnent le mieux.
Si votre prompt décrit une scène large mais que vous demandez un canevas portrait, le modèle devra recadrer ou déformer la composition. Faites correspondre la description au format. Pour les pipelines en aval, générez à la taille adaptée à votre cas d'usage le plus grand, puis réduisez ensuite ; une image agrandie à partir d'une petite taille est rarement correcte. Lorsque vous avez besoin de plusieurs formats, lancez des appels séparés pour chaque ratio plutôt que de recadrer une seule image en différentes mises en page.
Les réglages de sortie autres que le ratio d'aspect (indications de qualité, contrôles de style) sont propres au modèle. Ne définissez que ce qui est documenté sur la page du modèle, et considérez chaque paramètre supplémentaire comme une variable à tester, non comme une valeur par défaut à recopier.
Gérer les erreurs et les limites de débit
Les échecs d'une intégration en production sont prévisibles : clé erronée, paramètres invalides, délais d'attente et limitation de débit. Traitez chaque catégorie explicitement.
Valider avant d'analyser
Vérifiez d'abord le code de statut HTTP. 2xx signifie succès — analysez alors le corps de la réponse. 4xx signifie généralement que votre requête est problématique : clé non autorisée, JSON mal formé ou valeur de paramètre non prise en charge. Ces problèmes ne disparaîtront pas en réessayant ; journalisez le corps de la réponse, remontez-le à l'appelant et corrigez la requête. 5xx indique un problème côté serveur, généralement temporaire.
Réessayer avec un backoff
Ne réessayez que les échecs susceptibles de réussir plus tard : réponses 429, délais d'attente, erreurs de connexion et la plupart des codes 5xx. Utilisez un backoff exponentiel avec gigue — attendez un court intervalle de base, doublez à chaque tentative et fixez une limite au nombre total de tentatives. Ne réessayez jamais un 400 ou un 401 ; vous ne ferez que consommer votre quota inutilement.
import time, random
def generate(payload, max_attempts=5):
for attempt in range(max_attempts):
try:
r = requests.post(URL, headers=HEADERS, json=payload, timeout=60)
except requests.RequestException:
pass # erreur réseau : réessayer ci-dessous
else:
if r.status_code == 200:
return r.json()
if r.status_code not in (429, 500, 502, 503, 504):
raise RuntimeError(f"irrécupérable : {r.status_code} {r.text}")
time.sleep(min(2 ** attempt + random.random(), 30))
raise RuntimeError("tentatives épuisées")
Respecter les limites
Maintenez le volume de requêtes sous la limite de débit indiquée pour votre compte, et considérez un 429 comme un signal de ralentir, non de réessayer plus fort. Ajoutez un plafond de concurrence dans vos workers et journalisez l'identifiant de requête pour chaque tentative afin de diagnostiquer a posteriori les limitations et les échecs. Comme les appels d'image sont facturés sur la sortie générée, les tentatives qui produisent une image ne sont pas gratuites — validez les entrées avant d'envoyer la requête.
De l'appel de test à la liste de vérification de production
Avant la mise en production, vérifiez les points opérationnels suivants :
- Gestion des clés : les clés résident dans des variables d'environnement ou un gestionnaire de secrets, jamais dans le contrôle de version. Faites tourner les clés selon un calendrier, et immédiatement en cas de fuite suspectée.
- Délais d'attente : chaque appel sortant dispose d'un délai d'attente explicite, et votre appelant sait quoi faire lorsqu'il se déclenche.
- Journalisation : pour chaque appel, enregistrez l'identifiant de requête, la version du prompt, les paramètres, le statut et la latence. Masquez les clés et les charges utiles complètes si nécessaire.
- Versionnage des prompts : conservez les prompts ainsi que les réglages ayant produit les sorties acceptées, pour pouvoir reproduire et revenir en arrière.
- Sensibilité aux coûts : la génération est facturée sur la sortie, limitez donc la taille des lots, évitez les tentatives inutiles et mettez en cache les résultats que vous réutiliserez.
- Dégradation gracieuse : si la génération échoue après les tentatives, basculez vers une image en cache ou un espace réservé plutôt que de casser la page.
Commencez par l'appel curl unique de ce guide, déplacez-le dans une petite fonction utilitaire Python, puis seulement ajoutez la concurrence et le traitement par lots. À mesure que vous étendez votre intégration, la page de référence du modèle seedream-4.5/text-to-image est l'endroit où confirmer les noms de champs.
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