Blog

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

Nov 17, 2026
Image de couverture du blog hiapi.ai : des plans de béton gris chaud s'entrecroisent sous une lumière rasante, formant une composition géométrique minimaliste avec des faces d'ombre bleu-gris profond et de fins joints vert sauge.
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_ratio ou 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 Authorization porte 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/json indique 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 →

Commencez avec des artefacts IA persistants

Obtenez votre clé API et appelez des modèles d'image, de vidéo et d'audio via une API unique basée sur les tasks.

Lire la documentation de l'API