Tutoriel

Comment utiliser le mode image-vers-image de seedream-5.0-lite via l'API hiapi

Jul 7, 2026

Ce tutoriel vous montre comment appeler le mode image-vers-image de seedream-5.0-lite via l'API de tâches unifiée de hiapi : la structure exacte de la requête, une commande curl exécutable telle quelle, un script Python prêt à intégrer côté backend, ainsi que les pièges de validation que ce modèle impose et que les autres modèles n'appliquent pas.

À la fin de cet article, vous disposerez d'un script qui prend une ou plusieurs URL d'images de référence et un prompt d'édition, et renvoie l'URL d'une image générée immédiatement téléchargeable.

Ce qu'il vous faut

Un compte hiapi et une clé API. Vous pouvez les obtenir dans la console hiapi.
Une ou plusieurs images de référence hébergées sur des URL HTTPS publiques. Le modèle accepte jusqu'à 14 images de référence par requête, ce qui le rend utile pour les workflows multi-références : fusionner le sujet d'une image avec le style ou la scène d'une autre.
Un prompt textuel décrivant l'édition ou la transformation (au moins 3 caractères — oui, l'API vérifie cela).

Toutes les requêtes sont envoyées au point de terminaison unifié des tâches, avec la clé placée dans l'en-tête Authorization :

POST https://api.hiapi.ai/v1/tasks
Authorization: Bearer sk-<your-key>
Content-Type: application/json

Structure de la requête (et exigences de ce modèle)

L'id du modèle est seedream-5.0-lite/image-to-image — transmettez-le tel quel, exactement comme il apparaît dans /v1/models. Son schéma input est strict : les quatre champs sont tous obligatoires :

Champ	Type	Description
`prompt`	string	Instruction d'édition. Longueur minimale 3.
`image_urls`	string[]	1 à 14 URL d'images de référence.
`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`. Ce modèle n'a pas de palier 1K.

Deux pièges guettent souvent ceux qui migrent depuis d'autres modèles de la plateforme :

resolution n'accepte que 2K ou 4K. Si votre code commun de soumission de tâches remplit par défaut "1K" (ce qui fonctionne sur beaucoup d'autres modèles d'image), ce modèle le rejettera avec un 400.
Les champs superflus sont rejetés, pas ignorés. Envoyer size, n ou quoi que ce soit hors du schéma renvoie 400 INVALID_REQUEST avec additional properties '<field>' not allowed. L'API de tâches valide input par modèle — ne réutilisez pas aveuglément le payload d'un autre modèle.

Exemple minimal exécutable : curl

Créer la tâche :

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-lite/image-to-image",
    "input": {
      "prompt": "Replace the background with a sunlit Tokyo street at golden hour, keep the subject unchanged",
      "image_urls": ["https://your-cdn.example.com/subject.png"],
      "aspect_ratio": "3:2",
      "resolution": "2K"
    }
  }'

Une soumission réussie renvoie un id de tâche dans data :

{"code": 200, "data": {"taskId": "task_abc123..."}}

Interroger le résultat :

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

Pendant l'exécution, data.status vaut pending/processing. Une fois terminé, il passe à "success" et l'image apparaît dans data.output :

{
  "code": 200,
  "data": {
    "status": "success",
    "output": [{"url": "https://.../result.png", "expireAt": "..."}]
  }
}

L'URL de sortie a une durée de validité courte (notez le champ expireAt). Téléchargez immédiatement les octets et stockez-les vous-même — pas de hotlinking ni de persistance de l'URL d'origine.

Multi-références : transmettre plusieurs images

Pour fusionner plusieurs images de référence — par exemple une image de produit et une image de style — ajoutez simplement d'autres URL dans image_urls et précisez dans le prompt ce qu'apporte chaque image :

{
  "model": "seedream-5.0-lite/image-to-image",
  "input": {
    "prompt": "Place the product from the first image into the scene from the second image, matching its lighting and color grade",
    "image_urls": [
      "https://your-cdn.example.com/product.png",
      "https://your-cdn.example.com/scene-reference.jpg"
    ],
    "aspect_ratio": "1:1",
    "resolution": "2K"
  }
}

La limite stricte est de 14 URL ; la 15e renvoie 400 INVALID_REQUEST: image_urls: maxItems: got 15, want 14. En pratique, 2 à 4 images de référence soigneusement choisies, accompagnées d'un prompt attribuant explicitement un rôle à chaque image (« conserver le sujet de l'image 1, adopter la palette de couleurs de l'image 2 »), produisent des éditions bien plus contrôlées qu'une pile d'images vaguement liées.

Pour des éditions précises et ciblées sur une seule image — changer l'arrière-plan, modifier un vêtement, supprimer un objet — utilisez une seule URL de référence et précisez à la fois ce qui doit changer et ce qui doit être conservé (« garder le visage et la pose inchangés »). Les modèles Seedream suivent très bien les instructions de conservation ; les préciser explicitement est la clé qui distingue une édition précise d'une réinterprétation complète.

Python prêt pour la production : soumettre, interroger, télécharger

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-5.0-lite/image-to-image",
        "input": {
            "prompt": prompt,
            "image_urls": image_urls,
            "aspect_ratio": aspect_ratio,
            "resolution": resolution,  # this model: "2K" or "4K" only
        },
    }, timeout=60)
    body = resp.json()
    if resp.status_code != 200 or not (body.get("data") or {}).get("taskId"):
        raise RuntimeError(f"create failed [{resp.status_code}]: {body}")
    task_id = body["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().get("data") or {}
        if task.get("status") == "success":
            outputs = task.get("output") or []
            if not outputs or not outputs[0].get("url"):
                raise RuntimeError(f"task {task_id} succeeded but returned no output URL")
            # 3. Download immediately — the URL expires
            img = requests.get(outputs[0]["url"], timeout=120)
            img.raise_for_status()
            return img.content
        if task.get("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} still running after 600s")


if __name__ == "__main__":
    png = edit_image(
        "Replace the background with a minimalist studio backdrop, keep the subject unchanged",
        ["https://your-cdn.example.com/subject.png"],
        aspect_ratio="3:2",
    )
    with open("edited.png", "wb") as f:
        f.write(png)
    print(f"saved edited.png ({len(png)} bytes)")

Utiliser un callback au lieu du polling

Le polling convient bien aux scripts et aux files de workers. Pour un backend Web, enregistrez un callback à la création de la tâche pour que hiapi vous pousse l'état final — l'objet callback se place au niveau supérieur de la requête, juste à côté de model :

{
  "model": "seedream-5.0-lite/image-to-image",
  "input": { "...": "..." },
  "callback": {
    "url": "https://your-app.example.com/hooks/hiapi",
    "when": "final"
  }
}

Avec "when": "final", vous ne recevez qu'un seul POST lorsque la tâche passe en success ou fail. Deux règles pour votre gestionnaire :

Rendez-le idempotent. Utilisez l'id de tâche comme clé de traitement, afin qu'une livraison webhook en double n'entraîne pas un double traitement. Stockez l'id de tâche à la soumission et considérez le callback comme une notification « va chercher et termine », pas comme l'unique source de vérité.
Conservez un chemin de réconciliation. Si votre point de terminaison est indisponible au moment du callback, un balayage périodique des id non terminés avec un GET /v1/tasks/<id> permet de rattraper les manques.

Si votre callback semble ne jamais arriver, passez en revue les modes de défaillance courants, par ordre de probabilité, décrits dans pourquoi votre callback de tâche hiapi ne se déclenche pas.

Gestion des erreurs : les trois échecs qui comptent vraiment

401 permission_denied à la création — votre clé ne peut pas utiliser ce modèle. Le corps de la réponse ressemble à :

{"error": {"code": "permission_denied", "message": "This API key cannot use the selected model...", "type": "hiapi_error"}}

Vérifiez les permissions de modèle de la clé dans la console, ou utilisez une clé pour laquelle les modèles d'image sont activés.

400 INVALID_REQUEST à la création — votre input ne correspond pas au schéma de ce modèle. Le message liste tous les champs en infraction en une seule fois (par exemple resolution: value must be one of '2K', '4K'; <root>: additional properties 'size' not allowed), lisez-le donc en entier et corrigez tous les champs en une fois. Ce sont des erreurs permanentes — rejouer le même payload échouera toujours.

status: "fail" sur la tâche — la création a réussi mais la génération a échoué (URL de référence inaccessible côté backend, politique de contenu, capacité amont). Les champs error.code et error.message de la tâche expliquent pourquoi. Contrairement au 400, certaines de ces erreurs sont temporaires et méritent une nouvelle tentative avec backoff.

Bon à savoir également : un GET sur un id de tâche inexistant ou expiré renvoie 404 task not found — lors d'un balayage de réconciliation, traitez-le comme un état terminal, et non comme « toujours en attente ».

Où aller ensuite

Page du modèle seedream-5.0-lite/image-to-image — playground et facturation à l'image.
Tarifs hiapi — tarifs actuels de tous les modèles d'image.
Les meilleures API image-vers-image en 2026 — comparaison de seedream avec gpt-image-2 et d'autres sur les mêmes tâches d'édition.
Tutoriel image-vers-image de gpt-image-2 — même API de tâches, schéma input différent ; une bonne illustration de pourquoi un payload n'est pas portable entre modèles.
Documentation hiapi — référence complète de l'API de tâches.

FAQ

Combien d'images de référence puis-je transmettre au mode image-vers-image de seedream-5.0-lite ? Le tableau image_urls accepte jusqu'à 14 entrées. Au minimum une — ce champ est obligatoire, donc un appel purement texte-vers-image doit plutôt utiliser seedream-5.0-lite/text-to-image.

Pourquoi d'autres modèles acceptent-ils le 1K alors que je reçois « value must be one of '2K', '4K' » ? Le schéma d'entrée de l'API de tâches est défini par modèle. Le mode image-vers-image de seedream-5.0-lite ne propose que des sorties 2K et 4K ; d'autres modèles offrent un palier 1K. Ne réutilisez pas le payload d'un autre modèle sans vérifier.

Puis-je envoyer l'image de référence en base64 plutôt qu'en URL ? Le schéma de ce modèle accepte image_urls — un tableau d'URL. Hébergez l'image sur une URL HTTPS accessible (n'importe quel CDN, bucket de stockage objet ou URL présignée fait l'affaire) et transmettez cette URL.

Combien de temps prend une génération, et combien de temps l'URL de sortie reste-t-elle valide ? En général bien moins que le budget de polling de 600 secondes de l'exemple Python ci-dessus. L'URL de sortie porte un horodatage expireAt — téléchargez les octets et stockez-les dans votre propre stockage dès que la tâche réussit.

Le même code fonctionne-t-il pour le texte-vers-image de seedream-5.0-lite ? Le point de terminaison et le flux sont identiques, mais le texte-vers-image a son propre schéma input (sans image_urls). Remplacez l'id du modèle par seedream-5.0-lite/text-to-image et retirez les images de référence — puis validez avec un appel de test, car les champs obligatoires diffèrent selon les modes.

Combien coûte chaque image ? La tarification dépend de l'usage par génération et varie selon la résolution. Consultez les tarifs en temps réel sur la page de tarifs.