Comment utiliser seedream-5.0-flash via l'API hiapi : curl, Python et une requête exécutable

Ce que vous allez construire

Une intégration fonctionnelle qui appelle le modèle d'image seedream-5.0-flash de hiapi depuis curl et Python : soumettre une requête de génération d'image à partir d'un texte (ou d'édition d'image), interroger le résultat et télécharger l'URL de sortie. À la fin, vous disposerez d'un script prêt à être intégré dans votre propre projet.

Prérequis

• Un compte hiapi et une clé API. Obtenez-la depuis la console hiapi — la clé se présente sous la forme sk-....
• curl ou Python 3.8+ (pip install requests).
• Aucune bibliothèque de traitement d'image n'est nécessaire — seedream-5.0-flash accepte un simple prompt, ou un prompt accompagné d'une URL d'image d'entrée pour l'édition.

Référence complète du modèle : seedream-5.0-flash sur hiapi et la page de documentation de l'API.

Exemple minimal exécutable

hiapi expose tous les modèles de génération via un point de terminaison unifié : vous créez d'abord une tâche, puis vous l'interrogez (ou recevez un callback) jusqu'à son achèvement.

curl

# 1. Créer la tâche
curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-flash",
    "input": {
      "prompt": "a minimalist ceramic teapot on a wooden table, soft morning light, product photography",
      "size": "2K"
    }
  }'
# => {"code":0,"data":{"taskId":"task_xxx","status":"pending", ...}}

# 2. Interroger jusqu'à l'achèvement
curl -s https://api.hiapi.ai/v1/tasks/task_xxx \
  -H "Authorization: Bearer sk-<your-api-key>"
# => {"code":0,"data":{"taskId":"task_xxx","status":"success",
#      "output":[{"url":"https://...signed-url...","expireAt":"..."}]}}

Python

import time
import requests

API_KEY = "sk-<your-api-key>"
BASE_URL = "https://api.hiapi.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


def generate_image(prompt: str, size: str = "2K") -> str:
    create = requests.post(
        f"{BASE_URL}/tasks",
        headers=HEADERS,
        json={"model": "seedream-5.0-flash", "input": {"prompt": prompt, "size": size}},
        timeout=30,
    )
    create.raise_for_status()
    task_id = create.json()["data"]["taskId"]

    while True:
        poll = requests.get(f"{BASE_URL}/tasks/{task_id}", headers=HEADERS, timeout=30)
        poll.raise_for_status()
        data = poll.json()["data"]
        if data["status"] == "success":
            return data["output"][0]["url"]
        if data["status"] == "fail":
            raise RuntimeError(f"task failed: {data}")
        time.sleep(2)


if __name__ == "__main__":
    image_url = generate_image("a minimalist ceramic teapot on a wooden table, soft morning light")
    print(image_url)

Remarques sur l'objet input :

• prompt (obligatoire, 1–5000 caractères) — ce qu'il faut générer, ou ce qu'il faut modifier si vous passez également image.
• image (facultatif, chaîne ou tableau de jusqu'à 10 URL/URI data:image/... en base64) — passez ce paramètre pour éditer/prendre comme référence une image existante plutôt que de générer à partir de zéro. Omettre pour une génération purement texte-vers-image.
• size (facultatif, par défaut "2K") — l'une des valeurs prédéfinies 1K / 1.5K / 2K, ou une chaîne personnalisée LARGEURxHAUTEUR comme "1536x1024" (total de pixels entre 921 600 et 4 624 220, rapport largeur/hauteur entre 1:16 et 16:1).
• output_format (facultatif) — "jpeg" ou "png".
• background (facultatif, par défaut "opaque") — ne le définissez sur "transparent" que lors de l'édition d'images avec canal alpha.

Le champ output[].url de la réponse est un lien signé et à expiration (champ expireAt) — téléchargez-le ou ré-hébergez-le rapidement, plutôt que de conserver ce lien direct à long terme.

Modes de production

Utiliser un callback au lieu de l'interrogation

Pour les intégrations serveur à serveur, évitez l'interrogation et laissez hiapi vous notifier à la fin de la tâche. Ajoutez un objet callback de niveau supérieur à côté de model/input (ne le imbriquez pas dans input) :

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-flash",
    "input": {"prompt": "a minimalist ceramic teapot on a wooden table"},
    "callback": {"url": "https://yourapp.example.com/hooks/hiapi", "when": "final"}
  }'

when: "final" est actuellement la seule valeur prise en charge — lorsque la tâche atteint un état terminal (success ou fail), votre point de terminaison reçoit exactement un POST. Pour éviter les doublons en cas de nouvelle tentative de livraison, dédupliquez par taskId et vérifiez que votre point de terminaison est accessible via HTTPS avant de vous y fier en production.

Interrogation vs. callback

• Utilisez l'interrogation lors du prototypage, pour des scripts à durée de vie courte, ou si vous n'avez pas encore de point de terminaison HTTPS public. Simple, mais ajoute de la latence et des requêtes pour les tâches lentes.
• Utilisez un callback lorsque vous exploitez un service — aucune requête d'interrogation inutile, et vous êtes prévenu dès que la tâche est terminée. Nécessite une URL HTTPS accessible publiquement.

Idempotence

La génération d'images n'est pas idempotente en soi (le même prompt ne renvoie pas deux fois la même image), donc si votre flux de travail nécessite une sémantique de « réessayer sans double facturation », suivez le taskId de votre côté et vérifiez l'état de la tâche après un délai d'attente avant de soumettre à nouveau la même requête, plutôt que de réessayer aveuglément.

Gestion des erreurs

• 401 accompagné de permission_denied — votre clé API est manquante, mal formée ou révoquée :

  {"error":{"code":"permission_denied","message":"This API key is invalid. Check that it is correct or use another API key and try again.","type":"hiapi_error"}}
  

  Vérifiez bien que vous envoyez Authorization: Bearer sk-... (et non la clé brute seule), et que la clé n'a pas été renouvelée.

• 400 accompagné de INVALID_REQUEST — un champ n'a pas passé la validation. Le message vous indique précisément quel champ et pourquoi, par exemple un size hors limites. Corrigez ce champ et soumettez à nouveau ; ne réessayez pas tel quel.

• Échec au niveau de la tâche — l'appel HTTP peut réussir (200) alors que la tâche se termine par status: "fail" après traitement. Vérifiez toujours data.status dans la réponse d'interrogation/callback, et pas seulement le code HTTP de l'appel de création.

Liens internes associés

• Page du modèle seedream-5.0-flash — tarifs, limites et panneau d'essai en ligne.
• Créer une tâche (documentation) — schéma de requête complet pour POST /v1/tasks.
• Obtenir les détails d'une tâche (documentation) — structure de la réponse d'interrogation et valeurs de statut.
• Authentification (documentation) — comment les clés API et les en-têtes fonctionnent sur tous les points de terminaison hiapi.
• Tarifs hiapi — prix actuel par image pour seedream-5.0-flash et tous les autres modèles.
• Guide de l'API texte-vers-image seedream-5.0-pro — si vous avez besoin d'une sortie de résolution supérieure, consultez le modèle frère plus fidèle de la gamme Pro.

Questions fréquentes

seedream-5.0-flash est-il gratuit ? Non — il est facturé à l'image via votre clé API hiapi. Consultez la page des tarifs pour les taux actuels ; aucun accès en production n'est possible sans une clé valide.

seedream-5.0-flash prend-il en charge l'édition image-vers-image, pas seulement le texte-vers-image ? Oui. Ajoutez le champ image à côté de prompt (URL ou chaîne base64 data:image/..., ou tableau de jusqu'à 10 éléments), et le modèle éditera/fusionnera en se basant sur l'image de référence plutôt que de générer à partir de zéro.

Pourquoi ma requête renvoie-t-elle 200 sans image ? Un POST /v1/tasks renvoyant 200 signifie uniquement que la tâche a été acceptée — la génération est asynchrone. Interrogez GET /v1/tasks/<id> (ou attendez le callback) et vérifiez data.status ; l'URL de l'image n'apparaît que lorsque status vaut "success".

Puis-je demander une résolution personnalisée au lieu de 1K/1.5K/2K ? Oui — passez size sous la forme "LARGEURxHAUTEUR" (par exemple "1536x1024") au lieu d'une valeur prédéfinie. Le total de pixels doit être compris entre 921 600 et 4 624 220, et le rapport largeur/hauteur entre 1:16 et 16:1, sinon la requête renvoie 400.

Que devient l'URL de sortie après un certain temps ? L'output[].url renvoyé est une URL signée avec un horodatage expireAt — ce n'est pas un stockage permanent. Une fois la tâche réussie, téléchargez les octets ou copiez-les dans votre propre stockage dès que possible.

Mon callback ne s'est jamais déclenché — que dois-je vérifier en premier ? Vérifiez que votre callback.url est un point de terminaison HTTPS accessible publiquement (ni localhost ni une adresse uniquement interne), et que callback est un champ de niveau supérieur du corps de la requête — et non imbriqué dans input.