Comment utiliser seedream-4.5/image-to-image via l'API hiapi : curl, Python et requêtes fonctionnelles

Pour éditer une image avec seedream-4.5, il suffit d'envoyer un POST à l'API de tâches unifiée de hiapi, d'effectuer un court polling, puis de télécharger le résultat. Ce guide fournit une requête curl fonctionnelle et un script Python complet pour seedream-4.5/image-to-image, ainsi qu'une description précise des champs d'entrée (vérifiée contre l'API en ligne), l'utilisation de plusieurs images de référence, et les erreurs que vous rencontrerez réellement.

Ce que vous allez construire et ce qu'il vous faut

Objectif : envoyer une ou plusieurs images sources accompagnées d'instructions d'édition à seedream-4.5/image-to-image, et récupérer l'URL de l'image terminée.

Prérequis :

• Une clé API hiapi — à obtenir depuis votre console. Chaque requête ci-dessous l'utilise comme jeton Bearer.
• Les images sources doivent être hébergées sur des URL accessibles publiquement. L'API les récupère côté serveur ; les chemins de fichiers locaux ou les URL privées ne fonctionnent pas.

Le modèle s'exécute sur le point de terminaison de tâches asynchrone : POST /v1/tasks crée la tâche, GET /v1/tasks/<taskId> rapporte l'état, et l'image terminée apparaît dans data.output[0].url.

Description des champs d'entrée (vérifiée)

seedream-4.5/image-to-image possède quatre champs d'entrée obligatoires et n'accepte aucun autre champ — la description est stricte, les champs inconnus sont rejetés par une erreur 400 :

Champ	Type	Contrainte
prompt	string	Instructions d'édition
image_urls	tableau de chaînes	URL publiques, jusqu'à 14 images
aspect_ratio	string	l'une des valeurs 1:1, 4:3, 3:4, 16:9, 9:16, 2:3, 3:2, 21:9
resolution	string	uniquement 2K ou 4K

Deux points méritent attention : il n'y a pas de paramètre n (une sortie par tâche — pour plusieurs variantes, créez plusieurs tâches en parallèle) ; et contrairement à l'image-to-image de seedream-5.0-pro (qui accepte 1K/2K), la version 4.5 exige 2K ou 4K. Envoyer 1K ici renvoie une erreur de validation.

Requête minimale fonctionnelle : curl

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-4.5/image-to-image",
    "input": {
      "prompt": "Transformez cette photo produit en une photo studio propre sur un fond blanc continu avec des ombres douces",
      "image_urls": ["https://your-cdn.example.com/source.jpg"],
      "aspect_ratio": "1:1",
      "resolution": "2K"
    }
  }'

En cas de succès, la création renvoie l'ID de tâche dans data.taskId. Interrogez-le :

curl -s https://api.hiapi.ai/v1/tasks/<taskId> \
  -H "Authorization: Bearer sk-<your-key>"

Lorsque data.status atteint success, l'URL de l'image se trouve dans data.output[0].url. En cas de fail, la raison se trouve dans data.error.

Script Python complet

Aucun SDK nécessaire — juste requests et une boucle de polling :

import time
import requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
API_KEY = "sk-<your-key>"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

def edit_image(prompt: str, image_urls: list[str],
               aspect_ratio: str = "1:1", resolution: str = "2K") -> bytes:
    # 1. Create the task
    resp = requests.post(API_BASE, headers=HEADERS, json={
        "model": "seedream-4.5/image-to-image",
        "input": {
            "prompt": prompt,
            "image_urls": image_urls,   # public URLs, max 14
            "aspect_ratio": aspect_ratio,
            "resolution": resolution,   # "2K" or "4K"
        },
    }, timeout=60)
    resp.raise_for_status()
    task_id = resp.json()["data"]["taskId"]

    # 2. Poll until terminal state
    deadline = time.time() + 600
    while time.time() < deadline:
        task = requests.get(f"{API_BASE}/{task_id}",
                            headers=HEADERS, timeout=30).json()["data"]
        if task["status"] == "success":
            url = task["output"][0]["url"]
            # 3. Output URLs expire -- download immediately
            return requests.get(url, timeout=120).content
        if task["status"] == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        time.sleep(5)
    raise TimeoutError(f"task {task_id} did not finish in 600s")

png = edit_image(
    "Transformez cette photo produit en une photo studio propre sur un fond blanc continu",
    ["https://your-cdn.example.com/source.jpg"],
)
with open("edited.png", "wb") as f:
    f.write(png)

Notez le commentaire de l'étape 3 : les URL de sortie portent un horodatage d'expiration. Persistez immédiatement les octets dans votre propre stockage après la réussite de la tâche — ne vous contentez pas d'enregistrer l'URL renvoyée en espérant qu'elle fonctionne encore demain.

Édition avec plusieurs images de référence

image_urls accepte jusqu'à 14 images dans une même tâche. C'est un atout pour les tâches de transfert de style et de composition : passez l'image que vous voulez éditer ainsi que les images de référence, et décrivez dans le prompt comment les combiner.

{
  "model": "seedream-4.5/image-to-image",
  "input": {
    "prompt": "Appliquez l'étalonnage des couleurs et le style d'éclairage de la deuxième image à la première image, sans modifier le sujet",
    "image_urls": [
      "https://your-cdn.example.com/subject.jpg",
      "https://your-cdn.example.com/style-reference.jpg"
    ],
    "aspect_ratio": "3:2",
    "resolution": "2K"
  }
}

L'ordre a un sens pour le prompt, pas pour l'API — référez-vous aux images par leur position (« première image », « deuxième image ») afin que le modèle sache laquelle est laquelle.

Considérations pour la production

Utilisez un callback plutôt que le polling. Pour tout ce qui dépasse un script, ajoutez un objet callback au niveau racine lors de la création de la tâche et ignorez complètement la boucle de polling :

{
  "model": "seedream-4.5/image-to-image",
  "input": { "...": "..." },
  "callback": { "url": "https://yourapp.com/hooks/hiapi", "when": "final" }
}

À la fin de la tâche, hiapi envoie l'état final de la tâche par POST à votre URL. Le polling convient aux outils CLI et aux notebooks ; pour un backend web, le callback est le bon choix, faute de quoi vous immobiliserez un processus de travail pendant les dizaines de secondes nécessaires à une édition 2K.

Idempotence. La création de tâche n'est pas idempotente — réessayer la création après un délai d'attente réseau peut produire (et facturer) deux tâches. Stockez le taskId dès que vous l'obtenez et, lors d'une nouvelle tentative, vérifiez d'abord s'il existe déjà une tâche active avant d'en créer une nouvelle.

Gestion des erreurs. Les deux premiers types d'échecs que vous rencontrerez :

• 401 permission_denied — clé incorrecte, ou la clé n'a pas accès à ce modèle. Le corps de la réponse ressemble à {"error": {"code": "permission_denied", "message": "This API key cannot use the selected model...", "request_id": "..."}}. Indiquez le request_id lorsque vous contactez le support.
• 400 INVALID_REQUEST — violation de la description des champs, avec un message précis : valeur de resolution incorrecte, plus de 14 éléments dans image_urls, champ inconnu, ou image_urls qui n'est pas un tableau. Tout cela est intercepté avant l'exécution de la tâche, donc sans frais.

Une tâche en échec indique status: "fail" sur la tâche elle-même, avec un objet error — traitez cela comme un cas distinct des erreurs HTTP, comme le fait le script Python ci-dessus.

Tarification

Le coût par image dépend de la résolution. Consultez les tarifs actuels sur la page de tarification. Les requêtes rejetées à l'étape de validation (400) ne lancent jamais de tâche ; les erreurs de description des champs sont donc gratuites pendant l'intégration.

Lectures associées

• Page du modèle seedream-4.5/image-to-image — espace d'essai, tarification et référence complète des paramètres
• seedream-4.5/text-to-image — même série, génération à partir du prompt uniquement
• Guide image-to-image de seedream-5.0-pro — niveau plus récent, énumération de résolution différente
• Documentation hiapi — référence de l'API de tâches et authentification

Questions fréquentes

Puis-je passer un fichier local ou une image base64 au lieu d'une URL ? Non. image_urls doit être un tableau d'URL accessibles publiquement — la plateforme les récupère et les normalise côté serveur. Téléversez d'abord dans votre propre stockage (S3, R2, n'importe quel CDN), puis passez l'URL.

Combien d'images de référence seedream-4.5 image-to-image prend-il en charge ? Jusqu'à 14 par tâche. Au-delà, une erreur 400 est renvoyée avec le message contenant image_urls: maxItems.

Pourquoi est-ce que je reçois une erreur 400 quand je règle resolution sur 1K ? Le point de terminaison image-to-image 4.5 accepte uniquement 2K ou 4K. L'option 1K appartient à l'image-to-image de seedream-5.0-pro — les énumérations diffèrent selon les séries de niveaux.

Puis-je générer plusieurs variantes en une seule requête ? Non — la description des champs ne contient pas de paramètre n et rejette les champs inconnus. Créez une tâche par variante et exécutez-les en parallèle ; chaque tâche ne renvoie qu'une seule sortie.

Combien de temps les URL de résultat restent-elles valides ? Les URL de sortie sont signées et portent une durée d'expiration. Téléchargez et stockez vous-même les images dès que la tâche réussit, au lieu de faire un lien direct vers la sortie de la tâche.

Quelle est la différence entre une erreur HTTP et une tâche en échec ? Une erreur HTTP (400/401) signifie que la requête n'a jamais abouti à une tâche — corrigez la charge utile ou la clé et renvoyez-la. Une tâche terminée avec status: "fail" a été acceptée mais n'a pas pu s'achever ; la raison se trouve dans l'objet error de la tâche et, pour les échecs transitoires, réessayer avec les mêmes entrées est généralement la bonne approche.