Documentation de l'API de génération d'images SeeDream

Cet article présentera une documentation sur l’API de génération d’images SeeDream, qui permet de générer des images officielles de SeeDream en entrant des paramètres personnalisés.

Processus de demande

Pour utiliser l’API de génération d’images SeeDream, commencez par obtenir votre jeton API sur le tableau de bord Ace Data Cloud et conservez-le pour référence.

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, après quoi vous serez automatiquement renvoyé à la page actuelle. Un jeton API suffit pour appeler tous les services de la plateforme, sans avoir besoin de demander séparément pour chaque service. La première demande vous donnera un quota gratuit pour une expérience sans frais ; en cas de quota insuffisant, vous pouvez recharger votre solde général sur le tableau de bord.

📘 Documentation complète : API de génération d’images SeeDream →

Utilisation de base

Tout d’abord, comprenez la méthode d’utilisation de base, qui consiste à entrer un mot-clé prompt, une action action, et une taille d’image size, pour obtenir le résultat traité. Vous devez d’abord transmettre un champ action, dont la valeur est generate, puis nous devons également entrer le mot-clé, dont le contenu est le suivant :

Nous pouvons voir ici que nous avons défini les en-têtes de requête, y compris :

accept : le format de réponse souhaité, ici rempli avec application/json, c’est-à-dire au format JSON.
authorization : la clé pour appeler l’API, que vous pouvez sélectionner directement après la demande.

De plus, nous avons défini le corps de la requête, y compris :

prompt : le mot-clé.
model : le modèle de génération, par défaut doubao-seedream-5-0-260128 (SeeDream 5.0 Lite, le plus récent). Prend en charge doubao-seedream-5-0-pro-260628, doubao-seedream-5-0-260128 (accepte également l’alias officiel 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 une seule image, ne générant qu’une seule image, ne prend pas en charge la génération d’images séquentielles (sequential_image_generation), le streaming (stream) et la recherche en ligne (tools). Le model doit être passé sous forme de chaîne de modèle complète (comme doubao-seedream-5-0-260128), passer des abréviations comme doubao-seedream-5.0-lite renverra 400.
image : informations sur l’image d’entrée, prend en charge l’URL ou le codage Base64. doubao-seedream-5-0-pro-260628 prend en charge l’entrée d’une ou plusieurs images (2 à 10 images, à partir de la 2ème image, facturation par image), doubao-seedream-5-0-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828 prennent en charge l’entrée d’une ou plusieurs images.
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 mélangées. Méthode 1 | Spécifiez la résolution de l’image générée et décrivez le rapport hauteur/largeur 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-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écifiez les valeurs de pixels de largeur et de hauteur de l’image générée : par défaut 2048x2048, la plage de valeurs de pixels totaux et de rapport hauteur/largeur varie selon le modèle (par exemple, la plage de pixels totaux pour 5.0 Pro est [921600, 4624220], pour 5.0 Lite / 4.5, la limite inférieure des pixels totaux est de 3,686,400, pour 4.0, la limite inférieure est de 921,600).
sequential_image_generation : images groupées : un ensemble d’images associées générées en fonction de votre contenu d’entrée. doubao-seedream-5-0-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828 prennent en charge ce paramètre, par défaut disabled.
stream : contrôle si le mode de sortie en streaming est activé. doubao-seedream-5-0-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828 prennent en charge ce paramètre, par défaut false.
response_format : spécifie le format de retour de l’image générée. Par défaut, c’est url, mais prend également en charge b64_json.
watermark : si un filigrane doit être ajouté à l’image générée. Par défaut, c’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. Seuls doubao-seedream-5-0-pro-260628 et doubao-seedream-5-0-260128 prennent en charge.
tools : configure les outils que le modèle doit appeler, actuellement prend en charge web_search (recherche en ligne). Seul SeeDream 5.0 Lite prend en charge.
optimize_prompt_options : configuration d’optimisation des mots-clés. 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 : uniquement pris en charge par 5.0 Pro pour l’édition d’images uniques. transparent nécessite l’entrée d’une image PNG avec un canal alpha, et output_format doit être png ; opaque pour un fond opaque normal.
layer_decomposition : uniquement pris en charge par 5.0 Pro. Lorsqu’il est défini sur true, une image PNG/JPEG doit être fournie, le prompt peut être omis pour une séparation automatique, ou des éléments peuvent être spécifiés en langage naturel/<bbox> ; size prend en charge auto/1K/1.5K/2K. Ce mode ne peut pas être utilisé avec des images groupées, le streaming, la recherche en ligne ou background.
callback_url : l’URL pour laquelle les résultats doivent être rappelés.
async : si le traitement doit être effectué en mode asynchrone. Lorsqu’il est défini sur true, l’interface renvoie immédiatement task_id, sans avoir besoin de fournir callback_url, puis les résultats peuvent être obtenus par polling via /seedream/tasks.

Après avoir fait votre choix, vous pouvez constater que le code correspondant a également été généré à droite, comme illustré :

Cliquez sur le bouton « Essayer » pour effectuer un test, comme indiqué sur l’image ci-dessus, ici nous avons obtenu le résultat suivant :

{
  "success": true,
  "task_id": "81246f86-05ff-4d7d-9553-1013e0c1cd32",
  "trace_id": "ab50a78d-ab1f-457f-a46b-c2259cd5d35b",
  "data": [
    {
      "prompt": "Une photo réaliste d'un flacon de parfum en verre dépoli sur un ardoise noire mouillée, lumière clé softbox unique, gouttes d'eau, fond sombre et moody, 85mm macro.",
      "size": "2048x2048",
      "image_url": "https://platform2.cdn.acedata.cloud/seedream/901c6af6-e83a-4849-b233-295f6c20bacb.jpg"
    }
  ]
}

Les résultats contiennent plusieurs champs, décrits comme suit :

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

On peut voir que nous avons obtenu des informations d’image satisfaisantes, nous devons simplement obtenir l’image générée de SeeDream à partir de l’URL de l’image dans le résultat data. De plus, si vous souhaitez générer le code correspondant, vous pouvez le copier directement, par exemple, le code CURL est comme suit :

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-260128",
  "prompt": "Une photo réaliste d'un flacon de parfum en verre dépoli sur un ardoise noire mouillée, lumière clé softbox unique, gouttes d'eau, fond sombre et moody, 85mm macro."
}'

Édition de la tâche d’image

Si vous souhaitez éditer une image, le paramètre image doit d’abord contenir 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-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828 prennent tous en charge l’entrée d’image.
image : téléchargez l’image à éditer, une ou plusieurs.

Un exemple de remplissage est comme suit :

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": "Conservez la pose du modèle et la forme fluide du vêtement liquide inchangées. Changez le matériau des vêtements de métal argenté à de l'eau complètement transparente (ou du verre). À travers l'écoulement du liquide, les détails de la peau du modèle sont visibles. L'effet de lumière et d'ombre passe de la réflexion à la réfraction.",
  "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)

En cliquant sur exécuter, vous pouvez constater que vous obtiendrez immédiatement un résultat, comme suit :

{
  "success": true,
  "task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde",
  "trace_id": "131a40c3-2eaf-44c9-af28-c9b408577286",
  "data": [
    {
      "prompt": "Conservez la pose du modèle et la forme fluide du vêtement liquide inchangées. Changez le matériau des vêtements de métal argenté à de l'eau complètement transparente (ou du verre). À travers l'écoulement du liquide, les détails de la peau du modèle sont visibles. L'effet de lumière et d'ombre passe de la réflexion à la réfraction.",
      "size": "2048x2048",
      "image_url": "https://platform.cdn.acedata.cloud/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg"
    }
  ]
}

On peut voir que l’effet généré est l’effet d’édition de l’image d’origine, le résultat est similaire à celui ci-dessus.

Décomposition des couches (Seedream 5.0 Pro)

La décomposition des couches va diviser une image d’entrée en 1 image de fond et jusqu’à 16 couches PNG transparentes pouvant être éditées indépendamment. La requête suivante permet au modèle d’identifier automatiquement les éléments principaux ; si vous souhaitez spécifier des éléments, vous pouvez ajouter prompt, ou utiliser des coordonnées normalisées <bbox> dans le mot d’invite.

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 retournées sont classées par z_index de bas en haut. L’image de fond a un z_index de 0 ; les couches contiennent également name, description et bounding_box.absolute/normalized. Lors de la reconstruction avec des coordonnées absolues, les couches sont mises à l’échelle à [right-left, bottom-top], placées à [left, top], puis empilées par ordre croissant de z_index. Si une couche échoue à générer, toute la décomposition échoue.

Sortie en continu

Lorsque Lite/4.x est configuré avec stream: true, l’en-tête de la requête utilise accept: application/x-ndjson. L’interface renvoie ligne par ligne image_generation.partial_succeeded ou image_generation.partial_failed, et enfin renvoie un événement unique image_generation.completed et l’utilisation finale ; seul l’événement de complétion déclenche une facturation. Le mode de flux ne peut pas être utilisé avec async ou callback_url.

Rappel asynchrone

Étant donné que le temps de génération de l’API SeeDream Images Generation est relativement long, environ 1 à 2 minutes, si l’API ne répond pas pendant longtemps, la requête HTTP maintiendra la connexion, entraînant une consommation supplémentaire de ressources système, donc cette API propose également un support de rappel asynchrone. Le processus global est le suivant : lorsque le client initie la requête, il spécifie un champ callback_url supplémentaire, après que le client ait lancé la requête API, l’API renverra immédiatement un résultat, contenant un champ d’information task_id, représentant l’ID de la tâche actuelle. Lorsque la tâche est terminée, le résultat de l’image générée sera envoyé au callback_url spécifié par le client sous forme de POST JSON, qui inclut également le champ task_id, permettant ainsi de relier le résultat de la tâche par ID. Si vous n’avez pas d’adresse publique pour le rappel, vous pouvez également ne pas spécifier callback_url, mais définir le champ async sur true dans la requête. Dans ce cas, l’interface renverra également immédiatement task_id, mais ne poussera pas le résultat, vous devrez utiliser ce task_id pour appeler l’interface /seedream/tasks afin de vérifier l’état de la tâche pour obtenir le résultat final. Voyons comment procéder avec un exemple. En cliquant sur exécuter, vous pouvez constater que vous obtiendrez immédiatement un résultat, comme suit :

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

Le contenu est comme suit :

{
    "success": true,
    "task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde",
    "trace_id": "131a40c3-2eaf-44c9-af28-c9b408577286",
    "data": [
        {
            "prompt": "Conservez la pose du modèle et la forme fluide du vêtement liquide inchangées. Changez le matériau des vêtements de métal argenté à de l'eau complètement transparente (ou du verre). À travers le flux liquide, les détails de la peau du modèle sont visibles. L'effet de lumière et d'ombre passe de la réflexion à la réfraction.",
            "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 étant similaires à ceux ci-dessus, 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 invalides.
400 api_not_implemented : Mauvaise requête, probablement en raison de paramètres manquants ou invalides.
401 invalid_token : Non autorisé, jeton d’autorisation invalide ou manquant.
429 too_many_requests : Trop de requêtes, vous avez dépassé la limite de taux.
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": "échec de la récupération"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Conclusion

Grâce à ce document, vous avez compris comment utiliser l’API de génération d’images SeeDream, qui permet de générer des images en entrant des mots d’invite. Nous espérons que ce document vous aidera à mieux intégrer et utiliser cette API. Si vous avez des questions, n’hésitez pas à contacter notre équipe de support technique.

Démarrage

Chat IA

Image IA

Vidéo IA

Audio IA

Web & Données

CAPTCHA

Identité

Proxy

Avancé

Coding

Documentation de l'API de génération d'images SeeDream

Processus de demande

Utilisation de base

Édition de la tâche d’image

Décomposition des couches (Seedream 5.0 Pro)

Sortie en continu

Rappel asynchrone

Gestion des erreurs

Exemple de réponse d’erreur

Conclusion

​Processus de demande

​Utilisation de base

​Édition de la tâche d’image

​Décomposition des couches (Seedream 5.0 Pro)

​Sortie en continu

​Rappel asynchrone

​Gestion des erreurs

​Exemple de réponse d’erreur

​Conclusion

Processus de demande

Utilisation de base

Édition de la tâche d’image

Décomposition des couches (Seedream 5.0 Pro)

Sortie en continu

Rappel asynchrone

Gestion des erreurs

Exemple de réponse d’erreur

Conclusion