Comment utiliser seedream-5.0-pro/image-to-image via l'API hiapi : curl, Python et un exemple de requête exécutable

Seedream 5.0 Pro est le modèle d'image phare de ByteDance ; son point de terminaison image-to-image accepte une ou plusieurs images de référence ainsi qu'une instruction textuelle, et renvoie le résultat édité — restylisation, remplacement d'arrière-plan, nettoyage de photo produit, composition multi-images. Sur hiapi, il s'exécute sur l'API asynchrone unifiée tasks : vous créez d'abord une tâche, puis vous interrogez (ou recevez un callback), et enfin vous téléchargez la sortie. Chaque paramètre, valeur d'énumération et message d'erreur ci-dessous a été vérifié contre l'API en production avant la publication de ce guide.

Ce que vous allez construire, et ce dont vous avez besoin

Objectif : envoyer une image de référence et une instruction d'édition à seedream-5.0-pro/image-to-image, récupérer l'image éditée et l'enregistrer localement.

Vous avez besoin de deux choses :

1. Une clé API hiapi — obtenez-la depuis votre console. Elle doit être placée dans l'en-tête Authorization: Bearer sk-....
2. Des URL d'images accessibles publiquement — l'API récupère vos images de référence côté serveur, elles doivent donc être accessibles via HTTPS. Les URL présignées de votre propre bucket fonctionnent parfaitement ; localhost ou des chemins privés, non. Si une URL ne peut pas être récupérée, vous recevez une erreur normalisée, pas un échec silencieux.

Paramètres (vérifiés)

L'ID du modèle est seedream-5.0-pro/image-to-image, exactement tel que renvoyé par GET /v1/models. Les quatre champs d'entrée sont tous obligatoires :

Champ	Type	Obligatoire	Valeurs / description
prompt	string	oui	L'instruction d'édition.
image_urls	tableau de chaînes	oui	1 à 10 URL d'images accessibles publiquement. Toujours un tableau, même pour une seule image.
aspect_ratio	string	oui	match_input_image, 1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3, 21:9
resolution	string	oui	1K ou 2K

Deux pièges fréquents :

• Le schéma est strict. Les champs inconnus sont rejetés — envoyer n, size ou seed renvoie une 400 avec additional properties ... not allowed. Sur hiapi, le schéma d'entrée diffère d'un modèle à l'autre (certains utilisent size, d'autres aspect_ratio), ne copiez donc pas les champs d'une famille de modèles à l'autre.
• Ici, resolution n'accepte que 1K/2K. D'autres points de terminaison seedream acceptent des ensembles de résolutions différents ; il vaut donc mieux vérifier au cas par cas plutôt que de présumer.

Exemple minimal exécutable : curl

Créer la tâche :

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-pro/image-to-image",
    "input": {
      "prompt": "Transforme cette photo produit en une prise de vue studio propre sur fond blanc sans raccord, avec des ombres douces",
      "image_urls": ["https://your-bucket.example.com/product.jpg"],
      "aspect_ratio": "match_input_image",
      "resolution": "2K"
    }
  }'

En cas de création réussie, l'ID de tâche est renvoyé dans data.taskId (réponse simplifiée) :

{ "data": { "taskId": "<your-task-id>" } }

Interrogez jusqu'à ce que la tâche atteigne un état terminal :

curl -s https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

data.status finit par être success — l'URL de votre image se trouve dans data.output[0].url — ou fail, avec les détails dans data.error.code et data.error.message.

Script Python complet : créer, interroger, télécharger

Uniquement la bibliothèque standard — rien à installer :

import json
import time
import urllib.request

API = "https://api.hiapi.ai/v1/tasks"
KEY = "sk-YOUR_KEY"


def call(url, payload=None):
    req = urllib.request.Request(
        url,
        data=json.dumps(payload).encode() if payload is not None else None,
        headers={
            "Authorization": f"Bearer {KEY}",
            "Content-Type": "application/json",
        },
        method="POST" if payload is not None else "GET",
    )
    with urllib.request.urlopen(req) as resp:
        return json.load(resp)


# 1. Créer la tâche d'édition
create = call(API, {
    "model": "seedream-5.0-pro/image-to-image",
    "input": {
        "prompt": "Restyle ce salon en intérieur scandinave, conserve la disposition et les positions des fenêtres",
        "image_urls": ["https://your-bucket.example.com/room.jpg"],
        "aspect_ratio": "match_input_image",
        "resolution": "2K",
    },
})
task_id = create["data"]["taskId"]
print("tâche créée :", task_id)

# 2. Interroger jusqu'à l'état terminal
while True:
    task = call(f"{API}/{task_id}")["data"]
    if task["status"] == "success":
        break
    if task["status"] == "fail":
        err = task.get("error") or {}
        raise RuntimeError(f"échec de la tâche : {err.get('code')} {err.get('message')}")
    time.sleep(5)

# 3. Télécharger immédiatement -- les URL de sortie expirent
image_url = task["output"][0]["url"]
urllib.request.urlretrieve(image_url, "edited.png")
print("edited.png enregistré")

Considérations pour la production

Sur un serveur, privilégiez les callbacks à l'interrogation. Ajoutez un objet callback de premier niveau lors de la création de la tâche ; hiapi enverra un POST unique à votre point de terminaison lorsqu'elle atteindra un état terminal :

{
  "model": "seedream-5.0-pro/image-to-image",
  "input": { "...": "..." },
  "callback": { "url": "https://your-server.example.com/hiapi-hook", "when": "final" }
}

Dans votre gestionnaire, traitez le callback comme un signal, non comme une source de vérité : récupérez l'ID de tâche, puis redemandez vous-même GET /v1/tasks/<id> avant d'agir. Pour les scripts, notebooks et tâches ponctuelles, l'interrogation reste appropriée — maintenez simplement un intervalle d'environ 5 secondes.

Rendez les nouvelles tentatives idempotentes. Lors de la création d'une tâche, conservez votre propre correspondance image source → taskId. Si le processus plante en cours d'interrogation, rattachez-vous au taskId enregistré plutôt que de resoumettre l'édition — une resoumission génère une seconde tâche facturée.

Téléchargez la sortie immédiatement. L'URL dans data.output[0].url est limitée dans le temps (elle porte une date d'expiration). Téléchargez les octets et stockez-les dans votre propre bucket ; ne pointez jamais directement vers l'URL de sortie de la tâche dans du contenu destiné aux utilisateurs.

Erreurs que vous rencontrerez réellement :

• 401 avec permission_denied — clé API manquante ou mal formatée. Vérifiez que l'en-tête est exactement Authorization: Bearer sk-....
• 400 avec INVALID_REQUEST — violation du schéma d'entrée. Les messages d'erreur sont précis, par exemple resolution: value must be one of '1K', '2K' ou image_urls: maxItems: got 11, want 10.
• image_urls must be an array — vous avez passé une chaîne nue. Même pour une seule image, enveloppez-la dans une liste.

Étapes suivantes

• Page du modèle : seedream-5.0-pro/image-to-image — capacités et état actuel.
• Le prix par image est indiqué sur la page de tarification.
• Une option d'édition moins chère pour les pipelines à forte concurrence : comment utiliser seedream-5.0-lite image-to-image.
• Choisir entre les modèles : les meilleures API image-to-image de 2026 compare la même tâche d'édition sur trois modèles.
• Référence complète de l'API : documentation hiapi.

Questions fréquentes

Combien d'images de référence puis-je envoyer au maximum ? Jusqu'à 10 URL dans image_urls. Cette limite est appliquée côté serveur — 11 images renvoient maxItems: got 11, want 10.

La sortie peut-elle conserver le rapport d'aspect de l'image d'entrée ? Oui — définissez aspect_ratio sur match_input_image. Pour l'édition et la restylisation, c'est généralement ce que vous voulez ; ne choisissez un ratio explicite comme 16:9 que si vous recomposez délibérément l'image.

seedream-5.0-pro image-to-image prend-il en charge la 4K ? Non. Ce point de terminaison n'accepte que 1K et 2K. Si vous demandez autre chose, vous recevez une 400 avec la liste des valeurs autorisées.

Mes URL d'images doivent-elles être publiques ? Elles doivent être récupérables par les serveurs de hiapi via HTTPS. Les URL présignées (S3, R2, GCS) fonctionnent très bien et vous permettent de garder le bucket lui-même privé.

Combien coûte seedream-5.0-pro image-to-image par image ? La facturation se fait par image générée avec succès et varie selon la résolution — consultez la page de tarification en direct pour les tarifs actuels.

En quoi cela diffère-t-il de seedream-5.0-lite image-to-image ? Pro est le niveau phare, destiné aux éditions plus difficiles et à plus haute fidélité ; lite est l'option plus rapide et moins chère pour les gros volumes. La structure des requêtes est similaire ; le moyen le plus clair de trancher est donc d'exécuter la même tâche d'édition sur les deux — commencez par le guide lite et comparez le résultat avec vos propres images de référence.