Tutoriel API Seedream 5.5 : code Python, tarifs et résultats réels

Pour appeler l’API Seedream 5.5, envoyez un POST à https://api.seedrouter.ai/v1/images/generations avec "model": "seedream-5-5" et un prompt, conservez l’id de tâche renvoyé, puis interrogez GET /v1/tasks/{id} jusqu’à ce que le statut soit completed. La tâche terminée contient les URL des images. La même requête permet aussi de retoucher avec jusqu’à 10 images de référence, de créer des PNG au fond transparent et de décomposer une image en calques transparents.

ByteDance a lancé Seedream 5.5 le 9 novembre 2026 avec trois changements majeurs : des retouches plus stables sur de nombreux passages, une sortie transparente native et des images plus réalistes avec du petit texte plus net.^[1] Nous l’avons lancé trois fois sur SeedRouter le lendemain. Ce tutoriel s’appuie sur ces essais : le code envoyé, les résultats, les délais et les coûts. Chaque champ figure dans la référence de l’API Seedream 5.5, et le Playground se trouve sur la page du modèle.

De quoi avez-vous besoin avant le premier appel à l’API Seedream 5.5 ?

Deux choses : une clé API et l’ID de modèle. Il n’y a rien à télécharger. ByteDance n’a pas publié les poids de Seedream 5.5 ; le modèle fonctionne donc via une API hébergée et votre code envoie uniquement du JSON.

Créez une clé dans Clés API et conservez-la dans une variable d’environnement sur votre serveur, jamais dans du code navigateur :

export SEEDROUTER_API_KEY="your-key"
pip install requests

L’ID de modèle est seedream-5-5. Un seul ID couvre la génération à partir de texte, la retouche et la décomposition en calques ; les champs de la requête déterminent l’opération. Un nouveau compte reçoit un petit solde gratuit, suffisant pour quelques images de test en 1K avant de recharger.

Comment générer une image avec Python ?

L’envoi répond immédiatement avec une tâche, pas l’image. Ce script envoie un prompt, interroge toutes les 10 secondes, s’arrête après 15 minutes et enregistre chaque image reçue.

import os
import time
import requests

API = "https://api.seedrouter.ai/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"}


def submit(body):
    r = requests.post(f"{API}/images/generations", headers=HEADERS, json=body, timeout=60)
    r.raise_for_status()
    return r.json()["id"]


def wait(task_id, limit=900):
    deadline = time.time() + limit
    while time.time() < deadline:
        r = requests.get(f"{API}/tasks/{task_id}", headers=HEADERS, timeout=30)
        r.raise_for_status()
        task = r.json()
        if task["status"] in ("completed", "failed"):
            return task
        time.sleep(10)
    raise TimeoutError(f"{task_id} is still running; poll it again later")


task_id = submit({
    "model": "seedream-5-5",
    "prompt": "A ceramic teapot shaped like a sleeping fox on a linen tablecloth, "
              "soft morning window light, shallow depth of field. No text.",
    "size": "1K",
})
task = wait(task_id)
if task["status"] == "failed":
    raise RuntimeError(task["error"]["message"])

for i, image in enumerate(task["output"]["data"]):
    data = requests.get(image["url"], timeout=60).content
    with open(f"seedream-{i}.{image['output_format']}", "wb") as f:
        f.write(data)
    print(image["size"], image["url"])

C’est notre premier essai. Il s’est terminé en 47 secondes et a renvoyé un PNG de 1248 × 832.

Deux habitudes de cette boucle comptent en production. Si l’interrogation dépasse le délai, conservez l’identifiant de tâche et vérifiez à nouveau ; l’image peut encore être en cours de génération. Ne renvoyez pas la requête pour « réessayer », car cela crée une deuxième tâche et une deuxième facturation.

Quels champs de requête comptent ?

La plupart des requêtes n’ont besoin que de model, prompt et size. Voici les champs que vous définirez le plus souvent, avec leurs valeurs par défaut :

La sortie maximale est en 2K. Notre retouche en 16:9 et 2K a renvoyé 2560 × 1440, et les dimensions précises peuvent atteindre 4 624 220 pixels au total. Il n’y a pas de champ de format d’image : pour une forme fixe, envoyez des dimensions précises en pixels. Il n’existe pas de palier 3K ou 4K ; pour un fichier plus grand, il faudra donc l’agrandir ensuite. La référence de l’API répertorie tous les champs. Les champs qu’elle ne répertorie pas sont ignorés plutôt que rejetés : un seed, un style ou un n provenant d’une autre API d’images ne fera pas échouer la requête et n’aura aucun effet non plus. Une requête crée une image.

Comment retoucher une image avec des images de référence ?

Placez la source dans image et indiquez dans le prompt ce qu’il faut modifier et conserver. Notre deuxième essai a transformé une photo ensoleillée d’un peintre sur la coursive d’un phare en une nuit d’hiver :

task_id = submit({
    "model": "seedream-5-5",
    "prompt": "Turn this scene into a snowy winter night with warm light from "
              "the lighthouse windows, keep the composition",
    "image": "https://static.seedrouter.ai/media/landing/models/seedream-5-5/v1/lighthouse-source.webp",
    "size": "2560x1440",
})

Il a pris 40 secondes et a renvoyé un PNG de 2560 × 1440. Le peintre, sa pose, le pinceau, la corde enroulée, les deux pots de peinture et la rambarde sont tous restés en place. Des flocons, de la neige sur la coursive et ses épaules, un ciel sombre et des fenêtres éclairées au-dessus de la bande rouge ont été ajoutés.

Avec plusieurs références, désignez-les par leur ordre dans la liste (« la veste de l’image 2 »). Chaque image de référence est facturée, dès la première ; envoyez donc uniquement les images nécessaires à la retouche.

Pour cette version, ByteDance affirme surtout que les zones non retouchées restent identiques au pixel près au fil des retouches, avec des tests sur 100 passages consécutifs.^[1] Via l’API, une retouche en plusieurs passages est une boucle : récupérez l’URL d’une tâche terminée et transmettez-la dans image à la requête suivante. Nous n’avons pas encore exécuté nous-mêmes une longue chaîne ; nous ne pouvons donc pas confirmer les 100 passages annoncés. Chaque passage est une nouvelle tâche et facture son image de référence.

Comment obtenir un PNG transparent ?

Réglez background sur transparent et gardez output_format sur png. Cela fonctionne à partir d’un prompt seul ou avec des références :

task_id = submit({
    "model": "seedream-5-5",
    "prompt": "A glossy red enamel pin shaped like a cherry, product cutout",
    "background": "transparent",
    "size": "1K",
})

transparent avec jpeg est refusé avant la création d’une tâche, car JPEG n’a pas de canal alpha. ByteDance décrit une sortie RGBA native avec transparence totale et partielle et des contours soigneusement rendus, sans qu’il soit nécessaire de supprimer le fond séparément.^[1]

Comment décomposer une image en calques avec l’API ?

Envoyez exactement une image avec layer_decomposition: true. Notre troisième essai a décomposé une affiche de jazz avec la reconnaissance de texte activée et un maximum de quatre images en sortie :

task_id = submit({
    "model": "seedream-5-5",
    "image": "https://static.seedrouter.ai/media/landing/models/seedream-5-5/v1/poster-source.webp",
    "layer_decomposition": True,
    "size": "1K",
    "layer_decomposition_options": {"max_images": 4, "text_recognition": True},
})

Il a pris 39 secondes et a renvoyé quatre images : l’image de fond et trois calques transparents.

Les deux calques de texte sont revenus avec les mots reconnus. Le champ text_recognition du calque du titre contenait "BLUE TIDE\nSESSIONS", avec HTF Didot comme police estimée et #122C4D comme couleur, tandis que le calque de la ligne d’informations contenait "LIVE JAZZ · PIER 7 HALL · SATURDAY 9 PM". Chaque ligne a sa propre boîte englobante et son style ; vous pouvez donc ressaisir le texte avec votre propre police au même endroit.

Trois choses à savoir avant de vous fier au résultat :

• Les fichiers des calques sont plus grands que leurs boîtes. Le facteur diffère pour chaque calque : 1,74× pour le titre, 1,08× pour l’illustration et 2,59× pour la ligne d’informations. Redimensionnez chaque PNG à sa bounding_box.absolute avant de le placer, puis superposez les calques par ordre croissant de z_index.
• max_images est une limite maximale ; une limite basse fusionne des éléments. Avec quatre emplacements, le modèle a regroupé le saxophoniste, les vagues et le soleil corail dans un seul calque. Prévoyez assez de place pour le nombre d’éléments attendu.
• Un élément peut apparaître deux fois. Le soleil corail figurait dans le calque d’illustration et était aussi resté sur l’image de fond. Vérifiez l’image de fond avant de déplacer un calque.

Combien coûte l’API Seedream 5.5 ?

Vous payez par image, selon la taille de chacune, plus chaque image de référence. Les images jusqu’à 2,61 millions de pixels (1K et 1.5K) relèvent du palier inférieur ; 2K et les tailles supérieures relèvent du palier supérieur. Une décomposition en calques facture l’image de fond et chaque calque selon sa propre taille. Les tâches échouées ne sont pas facturées.

Nos trois essais du 10 novembre 2026 et ce qui a été facturé pour chacun :

Multipliez ces unités par les prix du tableau ci-dessus pour obtenir la facture. La décomposition mérite votre attention : elle a coûté quatre images, et non une, car l’image de fond et chaque calque sont facturés.

Pendant son exécution, une décomposition en calques réserve plus que ce qu’elle facture. À l’acceptation de la tâche, le solde nécessaire à max_images images est réservé, 30 si vous omettez ce champ, avec auto compté au palier supérieur. À la fin de la tâche, les images reçues sont facturées et le reste est libéré. Une décomposition sans max_images ni size exige donc au départ un solde suffisant pour 30 images au palier supérieur plus l’image d’entrée, même si elle renvoie quatre images. Définissez max_images sur une valeur proche du nombre d’éléments attendu et choisissez un palier, comme dans notre troisième essai (quatre images demandées, quatre renvoyées), pour que le montant réservé reste proche de la facture.

Quelles erreurs faut-il prévoir ?

Les références doivent être des URL HTTP(S) publiques. Les data URI en base64 sont refusées ; téléversez donc d’abord le fichier sur votre propre stockage. JPEG, PNG, WebP, BMP, TIFF, GIF, HEIC et HEIF sont acceptés, jusqu’à 30 Mo chacun. La liste complète des codes figure dans le catalogue des erreurs.

Questions fréquentes

Existe-t-il un Seedream 5.5 Pro ?

Pas encore. L’annonce de lancement de ByteDance indique "A Pro version of the Seedream 5.5 series will follow" (une version Pro de la série suivra) et ne donne aucune date.^[1] Aujourd’hui, l’API propose un modèle, seedream-5-5. Le modèle Pro de la génération précédente reste disponible sous le nom Seedream 5.0 Pro.

L’API Seedream 5.5 est-elle gratuite ?

Non. Elle est facturée par image à partir d’un solde prépayé, sans abonnement. Le petit solde gratuit d’un nouveau compte couvre quelques images en 1K ; vous pouvez donc exécuter le script ci-dessus avant de recharger.

Peut-on télécharger Seedream 5.5 ?

Non. ByteDance n’a pas publié les poids du modèle ; il n’existe donc aucun fichier à exécuter localement. Vous l’utilisez via une API comme celle-ci.

Combien d’images de référence puis-je envoyer ?

Jusqu’à 10 dans image. Une décomposition en calques en prend exactement une.

Combien de temps prend une requête ?

Nos trois essais ont pris de 39 à 47 secondes. Les décompositions qui renvoient beaucoup de calques peuvent prendre plusieurs minutes ; c’est pourquoi le script ci-dessus interroge pendant 15 minutes au maximum.

Références

1. ByteDance Seed. More Realistic Images, More Stable Editing Across 100 Rounds | Introducing Seedream 5.5. 9 novembre 2026. Consulté le 11 novembre 2026 sur seed.bytedance.com.
2. SeedRouter. Référence de l’API Seedream 5.5. /docs/seedream-5-5.