Guide d’intégration de l’API SeeDream Images Generation

Cet article présentera un guide d’intégration de l’API SeeDream Images Generation, qui permet de générer des images officielles SeeDream en saisissant des paramètres personnalisés.

Processus de demande

Pour utiliser l’API SeeDream Images Generation, rendez-vous d’abord sur la console Ace Data Cloud pour obtenir votre API Token et le conserver pour une utilisation ultérieure.

Si vous n’êtes pas encore connecté ou inscrit, vous serez automatiquement redirigé vers la page de connexion pour vous inviter à vous inscrire et à vous connecter ; une fois terminé, vous reviendrez automatiquement à la page actuelle. Un seul API Token permet d’appeler tous les services de la plateforme, sans avoir besoin d’en demander un séparément pour chaque service. Lors de la première demande, un quota gratuit est offert pour une expérience gratuite ; lorsque le quota est insuffisant, vous pouvez recharger votre solde général dans la console.

📘 Documentation complète : SeeDream Images Generation API →

Utilisation de base

Commençons par comprendre l’utilisation de base : il suffit de saisir le mot-clé prompt, l’action de génération action et la taille de l’image size pour obtenir le résultat traité. Il faut d’abord transmettre simplement un champ action, dont la valeur est generate, puis nous devons également saisir le mot-clé ; le contenu spécifique est le suivant :

Vous pouvez voir que nous avons défini ici les Request Headers, notamment :

accept : le format de résultat de réponse que vous souhaitez recevoir ; saisissez ici application/json, c’est-à-dire le format JSON.
authorization : la clé pour appeler l’API, qui peut être directement sélectionnée dans la liste déroulante après la demande.

Nous avons également défini le Request Body, notamment :

prompt : le mot-clé.
model : le modèle de génération, par défaut doubao-seedream-5-0-lite-260128 (SeeDream 5.0 Lite, le plus récent). Prend en charge doubao-seedream-5-0-pro-260628, doubao-seedream-5-0-lite-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828. Parmi eux, doubao-seedream-5-0-pro-260628 (SeeDream 5.0 Pro) est le modèle phare pour image unique, qui génère uniquement une seule image, et ne prend pas en charge les groupes d’images (sequential_image_generation), le streaming (stream) ni la recherche web (tools). model doit recevoir la chaîne complète du modèle (par exemple doubao-seedream-5-0-lite-260128) ; transmettre une forme abrégée comme doubao-seedream-5.0-lite renverra une erreur 400.
image : les informations de l’image d’entrée, prend en charge URL ou l’encodage Base64. doubao-seedream-5-0-pro-260628 prend en charge une ou plusieurs images en entrée (jusqu’à 10 images), tandis que doubao-seedream-5-0-lite-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828 prennent en charge une ou plusieurs images en entrée.
size : spécifie les informations de taille de l’image générée ; prend en charge les deux méthodes suivantes, qui ne peuvent pas être combinées. Méthode 1 | Spécifier la résolution de l’image générée, et décrire le rapport largeur-hauteur de l’image en langage naturel dans le prompt. Les préréglages pris en charge varient selon les modèles : doubao-seedream-5-0-pro-260628 prend en charge 1K/1.5K/2K ; doubao-seedream-5-0-lite-260128 prend en charge 2K/3K/4K ; doubao-seedream-4-5-251128 prend uniquement en charge 2K/4K ; doubao-seedream-4-0-250828 prend en charge 1K/2K/4K. Méthode 2 | Spécifier les valeurs en pixels de largeur et de hauteur de l’image générée : la valeur par défaut est 2048x2048, la plage du nombre total de pixels et du rapport largeur-hauteur varie selon le modèle (par exemple, pour 5.0 Pro, la plage totale de pixels est [921600, 4624220], la limite inférieure du total de pixels pour 5.0 Lite / 4.5 est de 3,686,400, et celle de 4.0 est de 921,600).
sequential_image_generation : groupe d’images : génère un ensemble d’images dont le contenu est lié, sur la base du contenu que vous saisissez. doubao-seedream-5-0-lite-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828 prennent en charge ce paramètre, avec disabled par défaut.
stream : contrôle l’activation du mode de sortie en streaming. doubao-seedream-5-0-lite-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828 prennent en charge ce paramètre, avec false par défaut.
response_format : spécifie le format de retour de l’image générée. La valeur par défaut est url, et b64_json est également pris en charge.
watermark : indique s’il faut ajouter un filigrane à l’image générée. La valeur par défaut est true.
output_format : spécifie le format de fichier de l’image générée ; prend en charge jpeg (par défaut) et png. Pris en charge uniquement par doubao-seedream-5-0-pro-260628 et doubao-seedream-5-0-lite-260128.
tools : configure les outils que le modèle doit appeler ; prend actuellement en charge web_search (recherche web). Pris en charge uniquement par Seedream 5.0 Lite.
optimize_prompt_options : configuration d’optimisation du prompt. 5.0 Pro prend en charge standard/fast ; 5.0 Lite et 4.5 prennent uniquement en charge standard ; 4.0 prend en charge standard/fast.
background : pris en charge uniquement pour l’édition d’image unique de 5.0 Pro. transparent exige de saisir un PNG avec un canal transparent, et output_format doit être png ; opaque correspond à un arrière-plan opaque ordinaire.
layer_decomposition : pris en charge uniquement par 5.0 Pro. Lorsqu’il est défini sur true, une image PNG/JPEG doit être saisie ; vous pouvez ne pas transmettre prompt pour effectuer une séparation automatique, ou spécifier des éléments en langage naturel/avec <bbox> ; size prend en charge auto/1K/1.5K/2K. Ce mode ne peut pas être utilisé avec les groupes d’images, le streaming, la recherche web ou background.
callback_url : l’URL qui doit recevoir le résultat de rappel.
async : indique si le traitement est effectué en mode asynchrone. Lorsqu’il est défini sur true, l’interface renvoie immédiatement task_id, sans nécessiter la fourniture de callback_url, puis le résultat est obtenu par interrogation via /seedream/tasks.

Après la sélection, vous pouvez constater que le code correspondant est également généré à droite, comme illustré ci-dessous :

Cliquez sur le bouton « Try » pour effectuer un test ; comme illustré ci-dessus, nous obtenons alors le résultat suivant :

{
  "success": true,
  "task_id": "80ceeed1-17d4-4eb7-82e0-18b34290f36e",
  "trace_id": "96b7fdc8-0fc8-4e2e-82a9-83c0a82f0a08",
  "data": [
    {
      "prompt": "A single matte blue cube centered on a clean white studio background, neutral lighting",
      "size": "2048x2048",
      "image_url": "https://cdn.acedata.cloud/assets/examples/seedream/db93b46e-c302-4676-8a11-63f0ba638a27-1c6f66f6b7e8.jpg"
    }
  ]
}

Le résultat renvoyé comporte plusieurs champs, présentés comme suit :

success，l’état actuel de la tâche de génération de vidéo.
task_id，l’ID actuel de la tâche de génération de vidéo.
trace_id，l’ID de suivi actuel de la génération de vidéo.
data，la liste des résultats de la tâche actuelle de génération d’images.
- image_url，le lien de la tâche actuelle de génération d’images.
- prompt，le prompt.
- size: les pixels de l’image générée

Nous pouvons voir que nous avons obtenu des informations d’image satisfaisantes, il nous suffit de récupérer l’image SeeDream générée à partir de l’adresse du lien d’image data dans le résultat. De plus, si vous souhaitez générer le code d’intégration correspondant, vous pouvez directement le copier, par exemple, le code CURL est le suivant :

curl -X POST 'https://api.acedata.cloud/seedream/images' \
-H 'accept: application/json' \
-H 'authorization: Bearer ${token}' \
-H 'content-type: application/json' \
-d '{
  "action": "generate",
  "model": "doubao-seedream-5-0-lite-260128",
  "prompt": "A single matte blue cube centered on a clean white studio background, neutral lighting"
}'

Tâche d’édition d’image

Si vous souhaitez éditer une image, le paramètre image doit d’abord obligatoirement transmettre le lien de l’image à éditer

model：le modèle utilisé pour cette tâche d’édition d’image, doubao-seedream-5-0-pro-260628、doubao-seedream-5-0-lite-260128、doubao-seedream-4-5-251128、doubao-seedream-4-0-250828 prennent tous en charge l’entrée d’images.
image：téléchargez une ou plusieurs images à éditer

L’exemple de remplissage est le suivant :

Le code correspondant :

import requests

url = "https://api.acedata.cloud/seedream/images"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "doubao-seedream-4-0-250828",
  "prompt": "Keep the model pose and the liquid garment flowing shape unchanged. Change the clothing material from silver metal to completely transparent water (or glass). Through the liquid flow, the details of the model skin are visible. The light and shadow effect shifts from reflection to refraction.",
  "image": ["https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_5_imageToimage.png"],
  "size": "2K",
  "watermark": False
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

Cliquez sur Exécuter, vous constaterez qu’un résultat sera immédiatement obtenu, comme suit :

{
  "success": true,
  "task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde",
  "trace_id": "131a40c3-2eaf-44c9-af28-c9b408577286",
  "data": [
    {
      "prompt": "Keep the model pose and the liquid garment flowing shape unchanged. Change the clothing material from silver metal to completely transparent water (or glass). Through the liquid flow, the details of the model skin are visible. The light and shadow effect shifts from reflection to refraction.",
      "size": "2048x2048",
      "image_url": "https://platform.cdn.acedata.cloud/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg"
    }
  ]
}

Nous pouvons voir que l’effet généré est un effet d’édition de l’image originale, le résultat est similaire à celui ci-dessus.

Séparation des calques（Seedream 5.0 Pro）

La séparation des calques divise une image d’entrée en 1 image de fond et jusqu’à 16 calques PNG transparents éditables indépendamment. La requête suivante permet au modèle d’identifier automatiquement les éléments principaux ; si vous devez spécifier des éléments, vous pouvez ajouter prompt, ou également utiliser des coordonnées <bbox> normalisées dans le prompt.

curl -X POST 'https://api.acedata.cloud/seedream/images' \
-H 'accept: application/json' \
-H 'authorization: Bearer ${token}' \
-H 'content-type: application/json' \
-d '{
  "model": "doubao-seedream-5-0-pro-260628",
  "image": "https://example.com/poster.png",
  "layer_decomposition": true,
  "size": "2K",
  "watermark": false
}'

Les data renvoyées sont classées de bas en haut selon z_index. Le z_index de l’image de fond est 0 ; les calques contiennent également name、description et bounding_box.absolute/normalized. Lors de la recomposition avec des coordonnées absolues, mettez le calque à l’échelle sur [right-left, bottom-top], placez-le sur [left, top], puis empilez-les par ordre croissant de z_index. Si la génération d’un quelconque calque échoue, l’ensemble de la séparation échoue.

Sortie en flux

Lorsque Lite/4.x définit stream: true, utilisez accept: application/x-ndjson dans l’en-tête de la requête. L’interface renvoie ligne par ligne image_generation.partial_succeeded ou image_generation.partial_failed, et renvoie finalement l’unique événement image_generation.completed ainsi que l’usage final ; seul l’événement de fin déclenche une facturation unique. Le mode flux ne peut pas être utilisé avec async ou callback_url.

Rappel asynchrone

Étant donné que le temps de génération de SeeDream Images Generation API est relativement long, environ 1 à 2 minutes, si l’API ne répond pas pendant longtemps, la requête HTTP restera connectée, entraînant une consommation supplémentaire de ressources système, cette API fournit donc également une prise en charge des rappels asynchrones. Le processus global est le suivant : lorsque le client initie une requête, il spécifie en supplément un champ callback_url, après que le client a initié une requête API, l’API renvoie immédiatement un résultat, contenant une information de champ task_id, représentant l’ID de la tâche actuelle. Une fois la tâche terminée, le résultat de l’image générée sera envoyé sous forme de POST JSON au callback_url spécifié par le client, qui inclut également le champ task_id, ainsi les résultats de la tâche peuvent être associés via l’ID. Si vous ne disposez pas d’une adresse publique disponible pour le rappel, vous pouvez également ne pas spécifier callback_url, mais définir le champ async sur true dans la requête. À ce moment-là, l’interface renverra également immédiatement task_id, mais ne poussera pas le résultat, vous devez transmettre ce task_id pour appeler l’interface /seedream/tasks afin d’interroger l’état de la tâche et obtenir le résultat final. Ci-dessous, nous allons comprendre comment procéder concrètement à travers un exemple. Cliquez sur Exécuter, vous constaterez qu’un résultat sera immédiatement obtenu, comme suit :

{
  "task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde"
}

Le contenu est le suivant :

{
    "success": true,
    "task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde",
    "trace_id": "131a40c3-2eaf-44c9-af28-c9b408577286",
    "data": [
        {
            "prompt": "Keep the model pose and the liquid garment flowing shape unchanged. Change the clothing material from silver metal to completely transparent water (or glass). Through the liquid flow, the details of the model skin are visible. The light and shadow effect shifts from reflection to refraction.",
            "size": "2048x2048",
            "image_url": "https://platform.cdn.acedata.cloud/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg"
        }
    ]
}

On peut voir qu’il y a un champ task_id dans le résultat, les autres champs sont similaires à ceux ci-dessus, et ce champ permet d’associer les tâches.

Gestion des erreurs

Lors de l’appel de l’API, si une erreur se produit, l’API renverra le code d’erreur et les informations correspondantes. Par exemple :

400 token_mismatched：Mauvaise requête, probablement en raison de paramètres manquants ou non valides.
400 api_not_implemented：Mauvaise requête, probablement en raison de paramètres manquants ou non valides.
401 invalid_token：Non autorisé, jeton d’autorisation non valide ou manquant.
429 too_many_requests：Trop de requêtes, vous avez dépassé la limite de débit.
500 api_error：Erreur interne du serveur, quelque chose s’est mal passé sur le serveur.

Exemple de réponse d’erreur

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Conclusion

Grâce à ce document, vous avez déjà compris comment utiliser l’API SeeDream Images Generation pour générer des images en saisissant des invites. Nous espérons que ce document vous aidera à mieux intégrer et utiliser cette API. Si vous avez des questions, veuillez contacter notre équipe de support technique à tout moment.

Démarrage

Chat IA

Image IA

Vidéo IA

Audio IA

Web & Données

CAPTCHA

Identité

Coding

Autres guides

Guide d’intégration de l’API SeeDream Images Generation

Processus de demande

Utilisation de base

Tâche d’édition d’image

Séparation des calques（Seedream 5.0 Pro）

Sortie en flux

Rappel asynchrone

Gestion des erreurs

Exemple de réponse d’erreur

Conclusion

​Processus de demande

​Utilisation de base

​Tâche d’édition d’image

​Séparation des calques（Seedream 5.0 Pro）

​Sortie en flux

​Rappel asynchrone

​Gestion des erreurs

​Exemple de réponse d’erreur

​Conclusion

Processus de demande

Utilisation de base

Tâche d’édition d’image

Séparation des calques（Seedream 5.0 Pro）

Sortie en flux

Rappel asynchrone

Gestion des erreurs

Exemple de réponse d’erreur

Conclusion