Comment appeler seedream-5.0-lite/text-to-image via l'API HiAPI : guide curl et Python

Ce que fait réellement cette intégration

Lancer un appel de génération d'images à partir de texte sur HiAPI, c'est un bref dialogue entre votre code et une file d'attente de tâches asynchrones. Vous envoyez une requête qui décrit l'image souhaitée ; la plateforme valide la requête, accepte la tâche et renvoie un identifiant. L'image ne se trouve pas dans la première réponse — elle est générée ensuite. Votre code surveille alors la tâche jusqu'à ce qu'elle signale son achèvement, puis télécharge l'image depuis l'URL exposée par la tâche.

Cette forme est importante, car elle détermine la manière dont vous écrivez l'intégration. Il y a trois moments distincts : la soumission, l'interrogation répétée (polling) et la récupération. Chacun a ses propres modes d'échec. La soumission échoue lorsque la charge utile est mal formée ou que le chemin du modèle est invalide. L'interrogation échoue lorsque la boucle est mal écrite — trop rapide, trop courte, ou incapable de distinguer « toujours en cours » de « terminé ». La récupération échoue lorsque vous traitez l'URL de sortie comme une adresse permanente ou que vous oubliez d'écrire les octets sur le disque.

Sous le capot, seedream-5.0-lite/text-to-image est un modèle générique de génération d'images à partir de texte sur la plateforme HiAPI. Vous l'appelez via cet identifiant de modèle exact. Les paramètres que vous envoyez sont les paramètres ordinaires de ce type d'appel : le nom du modèle, le prompt, ainsi que tout paramètre de contrôle de la taille ou du nombre de sorties indiqué dans la documentation du point de terminaison. Vous n'avez besoin d'aucun SDK particulier ; un simple client HTTPS suffit.

À la fin de cet exercice, vous disposerez d'une requête reproductible avec curl, d'une fonction Python qui l'encapsule, d'astuces pour formuler vos prompts afin que le texte rendu soit net et lisible, et d'une boucle d'interrogation qui se termine réellement. Tout passe par le même point de terminaison HiAPI, donc une fois qu'un appel réussit, il ne reste plus qu'à ajuster les paramètres.

Construire la requête avec curl

Commencez par la ligne de commande. Un appel curl fonctionnel est la référence de la charge utile — une fois qu'il réussit, chaque autre langage n'est qu'un exercice de traduction.

Deux éléments vous sont nécessaires avant le premier appel : votre clé d'API HiAPI et l'URL de base de l'API. La clé se place dans l'en-tête Authorization sous forme de jeton bearer. Gardez-la autant que possible hors de l'historique de votre shell ; une variable d'environnement est l'habitude la plus simple.

export HIAPI_API_KEY="your_api_key_here"

La requête elle-même est un POST avec un corps JSON. L'identifiant du modèle est le segment de chemin que vous appelez, et le prompt décrit l'image :

curl -sS -X POST "$HIAPI_BASE_URL" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-lite/text-to-image",
    "prompt": "A minimalist poster for a coffee shop called North Roast, warm cream background, bold dark lettering"
  }'

Définissez HIAPI_BASE_URL sur le point de terminaison de soumission de génération d'images à partir de texte indiqué dans la documentation de la plateforme ; le chemin varie selon l'interface du produit, donc copiez-le plutôt que de le deviner.

Avant d'écrire davantage de code, lisez la réponse. Une soumission réussie renvoie un objet JSON contenant un identifiant de tâche et un champ de statut. Le statut indique généralement que la tâche est en file d'attente ou en cours de traitement — pas encore terminée. C'est le comportement attendu. Notez précisément les noms des champs renvoyés ; vous les utiliserez dans les deux sections suivantes.

Deux erreurs au niveau de curl expliquent la plupart des échecs lors d'un premier essai. La première est une clé absente ou mal portée : la réponse est une erreur d'authentification, pas une erreur de modèle. La seconde est un corps mal formé — guillemets non échappés dans le prompt, virgule finale, guillemets simples là où le JSON exige des guillemets doubles. Si la plateforme rejette la charge utile, mettez-la en forme avec jq et validez-la séparément avant d'accuser le modèle.

Lorsque la soumission renvoie un identifiant, vous disposez d'une requête valide. Tout le reste n'est qu'attente et récupération.

Porter le code en Python

La version Python doit être une petite fonction réutilisable — pas un script avec un seul prompt codé en dur. Utilisez requests (ou httpx si vous préférez) ; l'appel lui-même ne nécessite aucun client particulier.

import os
import requests

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

HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

def submit_image(prompt: str, **params) -> dict:
    payload = {
        "model": "seedream-5.0-lite/text-to-image",
        "prompt": prompt,
        **params,
    }
    response = requests.post(BASE_URL, headers=HEADERS, json=payload, timeout=30)
    response.raise_for_status()
    return response.json()

Trois choix sont intentionnels ici. La clé et l'URL de base proviennent de l'environnement, de sorte que la fonction peut être soumise en toute sécurité. Le paramètre fourre-tout **params vous permet de transmettre la taille de sortie ou d'autres options documentées sans modifier la fonction. Et raise_for_status() transforme immédiatement les erreurs HTTP en exceptions, ce qui est exactement ce que vous voulez — un 4xx à la soumission ne deviendra jamais une tâche valide, donc échouer rapidement vaut mieux que d'inspecter un corps de réponse déroutant.

Le dictionnaire renvoyé constitue votre fiche de tâche. Affichez-le une fois pendant le développement pour connaître les noms exacts des clés de l'identifiant et du statut. Ne l'indexez pas à l'aveugle ; un petit accesseur garde le reste du code lisible :

job = submit_image("A flat illustration of a paper plane over a city map")
print(job)

S'il affiche une tâche en file d'attente, le portage depuis curl est correct. S'il lève une exception, le message de raise_for_status() vous indiquera si vous avez affaire à un problème d'authentification ou de charge utile — les deux mêmes catégories de problèmes que vous rencontreriez dans le shell.

Rédiger des prompts pour les connaissances générales et le texte rendu

Les modèles de génération d'images à partir de texte sont les plus performants lorsque le prompt décrit ce qui doit être visible, et les plus faibles lorsqu'il sous-entend des connaissances que le modèle doit déduire. seedream-5.0-lite/text-to-image peut exploiter un contexte général du monde — objets reconnaissables, conventions de design courantes, styles typographiques — mais vous devez tout de même lui fournir suffisamment de contenu pour ancrer ce contexte.

Pour les prompts de scène, décrivez le sujet, la composition et le style visuel. « A cozy reading nook by a window, soft afternoon light, three-quarter view, muted earth tones » indique au modèle à la fois quoi dessiner et comment le styliser. Un prompt vague produit une image banale ; un prompt précis produit une image exploitable.

Le texte rendu est là où les prompts échouent généralement. Si vous avez besoin de texte dans l'image, suivez quelques règles :

• Citez la chaîne exacte. Placez le texte souhaité entre guillemets pour qu'il soit clairement littéral et non descriptif.
• Restez bref. Un titre court ou un nom de marque se rend de façon fiable ; un paragraphe, non.
• Précisez la position et le style. « The word "North" centered at the top in a bold sans-serif » vaut mieux que « some text at the top ».
• Évitez les textes concurrents. Plusieurs éléments textuels distincts dans une même image produisent facilement du charabia. Si vous en avez besoin de plusieurs, gardez-les courts et éloignés les uns des autres.
• Ne modifiez qu'une variable à la fois. Changez la formulation, pas simultanément la formulation, la mise en page et le style, sinon vous ne saurez pas ce qui a résolu le problème.

Pour tout ce qui implique un contexte reconnaissable — catégorie de produit, type d'affiche, type d'enseigne — nommez-le explicitement. Les connaissances préalables du modèle sont plus utiles lorsque le prompt lui donne un point d'accroche. « A vintage travel poster for a coastal town » porte plus de contexte exploitable que « a poster ».

N'inventez pas de paramètres. Si le prompt ne produit pas la position de texte souhaitée, ajustez d'abord la formulation du prompt lui-même avant d'essayer des options non documentées.

Gérer les tâches asynchrones et télécharger la sortie

L'interrogation répétée est l'endroit où l'intégration échoue discrètement. La tâche est asynchrone, vous avez donc besoin d'une boucle qui vérifie le statut, attend entre les vérifications, finit par abandonner, et sait exactement quelles valeurs de statut signifient « terminé ».

import time

def wait_for_job(job_id: str, poll_interval: float = 3.0, timeout: float = 180.0) -> dict:
    deadline = time.monotonic() + timeout
    while time.monotonic() < deadline:
        response = requests.get(
            f"{BASE_URL}/{job_id}", headers=HEADERS, timeout=30
        )
        response.raise_for_status()
        job = response.json()

        status = job.get("status")
        if status in {"succeeded", "completed"}:
            return job
        if status in {"failed", "error", "cancelled"}:
            raise RuntimeError(f"Job {job_id} ended with status {status}")

        time.sleep(poll_interval)
    raise TimeoutError(f"Job {job_id} did not finish within {timeout}s")

Adaptez le chemin d'interrogation et les chaînes de statut à ce que montre la documentation de la plateforme — ces deux détails sont les plus susceptibles de différer du brouillon ci-dessus. La structure est ce qui compte : une échéance monotone, une pause entre les vérifications, des ensembles explicites de succès et d'échec, et un délai d'expiration qui lève une exception plutôt que de renvoyer une tâche à moitié terminée.

Une fois que la tâche signale un succès, la réponse contient l'URL de la sortie. Considérez cette URL comme temporaire. Téléchargez les octets immédiatement au lieu de stocker le lien :

def download_image(url: str, path: str) -> None:
    response = requests.get(url, timeout=60)
    response.raise_for_status()
    with open(path, "wb") as f:
        f.write(response.content)

job = wait_for_job(job_id)
download_image(job["output"]["url"], "out.png")

Avant de continuer, vérifiez que le fichier est bien une image réelle — ouvrez-le, vérifiez ses dimensions, ou au moins vérifiez que la taille en octets n'est pas anormalement petite. Si le serveur ferme proprement la connexion, un téléchargement tronqué apparaît comme un succès aux yeux de requests.

Erreurs courantes et comment les corriger

La plupart des échecs lors d'une première intégration se répartissent en quatre catégories. Traitez-les dans l'ordre.

Soumission rejetée

Si le premier appel renvoie un 4xx, affichez le corps de la réponse. Une erreur d'authentification signifie que la clé est absente, expirée ou n'est pas envoyée comme jeton bearer. Une erreur de schéma signifie que la charge utile est mal formée — mauvais champ de modèle, prompt manquant ou paramètre documenté mal orthographié. Validez le JSON séparément et comparez-le avec l'exemple curl fonctionnel.

La tâche ne se termine jamais

La boucle tourne indéfiniment ou expire. Vérifiez d'abord l'intervalle d'interrogation : marteler le point de terminaison sans pause peut déclencher une limitation de débit, faisant paraître une tâche saine comme bloquée. Vérifiez ensuite votre comparaison de statut — si la plateforme renvoie success et que vous testez succeeded, chaque tâche paraîtra inachevée. Enregistrez une fois la valeur de statut brute au lieu de deviner.

L'URL de sortie renvoie 404 ou 403

Les URL de sortie sont signées et limitées dans le temps. Si vous avez attendu longtemps avant de récupérer, le lien a peut-être expiré. Récupérez immédiatement après l'achèvement et, si vous devez conserver le résultat, enregistrez le fichier plutôt que le lien.

L'image est rendue mais le texte est illisible

C'est un problème de prompt, pas de code. Raccourcissez le texte, citez-le précisément, réduisez le nombre d'éléments textuels et rendez les instructions de style plus explicites. Relancez en ne changeant qu'une chose à la fois, afin de savoir quel ajustement a aidé.

La requête se bloque ou expire

Définissez toujours des délais d'expiration explicites sur les appels de soumission et d'interrogation. Une requête sans délai d'expiration peut bloquer indéfiniment un processus worker, et une boucle d'interrogation sans échéance transforme une interruption transitoire en processus bloqué.

En cas de comportement inattendu, réduisez-le à l'appel curl minimal qui échoue encore. Si la requête HTTP brute se comporte anormalement, la couche Python n'est pas en cause — une fois que curl fonctionne de nouveau, le portage vers Python est mécanique. La page du modèle seedream-5.0-lite/text-to-image liste les paramètres et la forme de réponse actuels, donc consultez-la avant de supposer des noms de champs.