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

Ce document présente 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, vous devez d’abord demander le service correspondant sur la page SeeDream Images Generation API. Une fois sur la page, cliquez sur le bouton « Acquire », comme illustré ci-dessous :

Si vous n’êtes pas encore connecté ou inscrit, vous serez automatiquement redirigé vers la page de connexion pour vous inscrire et vous connecter. Après connexion ou inscription, vous serez automatiquement renvoyé à la page actuelle. Lors de la première demande, un quota gratuit est offert, vous permettant d’utiliser l’API gratuitement.

Utilisation de base

Commençons par comprendre la méthode d’utilisation de base : en saisissant un mot-clé prompt, une action action et une taille d’image size, vous obtiendrez le résultat traité. Il faut d’abord transmettre un champ action avec la valeur generate, puis saisir le mot-clé. Le contenu spécifique est le suivant :

Ici, on peut voir que nous avons configuré les en-têtes de la requête, notamment :

accept : le format de réponse souhaité, ici application/json pour le format JSON.
authorization : la clé d’API pour appeler l’API, sélectionnable directement après la demande.

Le corps de la requête comprend :

prompt : le mot-clé.
model : le modèle de génération, par défaut doubao-seedream-5.0-lite. Sont supportés doubao-seedream-5.0-lite (le plus récent), doubao-seedream-4.5, doubao-seedream-4.0, doubao-seedream-3.0-t2i, doubao-seededit-3.0-i2i.
image : informations sur l’image d’entrée, supportant URL ou encodage Base64. Les modèles doubao-seedream-5.0-lite, doubao-seedream-4.5, doubao-seedream-4.0 acceptent une ou plusieurs images, doubao-seededit-3.0-i2i supporte une seule image, doubao-seedream-3.0-t2i ne supporte pas ce paramètre.
size : spécifie la taille de l’image générée, avec deux modes incompatibles entre eux. Mode 1 | spécifier la résolution de l’image générée et décrire le ratio largeur/hauteur en langage naturel dans le prompt. Les préréglages varient selon les modèles : doubao-seedream-5.0-lite supporte 2K/3K/4K ; doubao-seedream-4.5 supporte uniquement 2K/4K ; doubao-seedream-4.0 supporte 1K/2K/4K ; doubao-seedream-3.0-t2i et doubao-seededit-3.0-i2i ne supportent pas les préréglages, acceptent uniquement le mode 2. Mode 2 | spécifier la largeur et la hauteur en pixels : par défaut 2048x2048, la plage de pixels totaux et de ratio varie selon le modèle (par exemple 5.0 / 4.5 ont un minimum de 3 686 400 pixels, 4.0 a un minimum de 921 600, 3.0-t2i / seededit-3.0-i2i acceptent de 512x512 à 2048x2048).
seed : graine aléatoire pour contrôler la randomisation du contenu généré. Plage de valeurs [-1, 2147483647]. Supporté uniquement par doubao-seedream-3.0-t2i.
sequential_image_generation : génération d’une série d’images liées basées sur votre entrée. Supporté par doubao-seedream-5.0-lite, doubao-seedream-4.5, doubao-seedream-4.0, par défaut disabled.
stream : contrôle le mode de sortie en flux continu. Supporté par doubao-seedream-5.0-lite, doubao-seedream-4.5, doubao-seedream-4.0, par défaut false.
guidance_scale : degré de correspondance entre le résultat du modèle et le prompt, plus la valeur est élevée, plus la corrélation est forte. Plage [1, 10]. Par défaut 2.5 pour doubao-seedream-3.0-t2i, 5.5 pour doubao-seededit-3.0-i2i, non supporté par les autres modèles.
response_format : format de retour de l’image générée. Par défaut url, supporte aussi b64_json.
watermark : indique si un filigrane doit être ajouté à l’image générée. Par défaut true.
output_format : format du fichier image généré, supporte jpeg (par défaut) et png. Supporté uniquement par doubao-seedream-5.0-lite.
tools : configuration des outils que le modèle doit appeler, actuellement supporte web_search (recherche en ligne). Supporté uniquement par doubao-seedream-5.0-lite.
callback_url : URL pour le rappel des résultats.

Après sélection, le code correspondant est généré à droite, comme illustré :

Cliquez sur le bouton « Try » pour tester. Comme dans l’exemple ci-dessus, nous obtenons le résultat suivant :

{
  "success": true,
  "task_id": "25027ba3-0430-4a1b-91c8-d2297f19ba73",
  "trace_id": "8043a9e9-692f-43b0-82f7-5890f798be38",
  "data": [
    {
      "prompt": "a white siamese cat",
      "size": "2048x2048",
      "image_url": "https://platform.cdn.xhuoapi.ai/seedream/3c060029-69b1-406f-a957-fcd55ddc9386.jpg"
    }
  ]
}

Le résultat contient plusieurs champs, décrits ci-dessous :

success : état de la tâche de génération d’image.
task_id : ID de la tâche de génération.
trace_id : ID de suivi de la tâche.
data : liste des résultats de génération d’image.
- image_url : lien vers l’image générée.
- prompt : mot-clé.
- size : résolution de l’image générée.

On peut voir que nous avons obtenu une image satisfaisante, il suffit de récupérer l’image SeeDream générée via le lien dans data. Si vous souhaitez générer le code d’intégration correspondant, vous pouvez copier directement, par exemple le code CURL suivant :

curl -X POST 'https://api.xhuoapi.ai/v1/seedream/images' \
-H 'accept: application/json' \
-H 'authorization: Bearer ${token}' \
-H 'content-type: application/json' \
-d '{
  "action": "generate",
  "model": "doubao-seedream-4-0-250828",
  "prompt": "a white siamese cat"
}'

Tâche d’édition d’image

Pour éditer une image, le paramètre image doit contenir le lien de l’image à modifier.

model : modèle utilisé pour la tâche d’édition, doubao-seedream-5.0-lite, doubao-seedream-4.5, doubao-seedream-4.0 supportent une ou plusieurs images, doubao-seededit-3.0-i2i supporte une seule image.
image : image(s) à éditer, une ou plusieurs.

Exemple de saisie :

Code correspondant :

import requests

url = "https://api.xhuoapi.ai/v1/flux/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)

Après exécution, un résultat est 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.xhuoapi.ai/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg"
        }
    ]
}

On constate que l’effet généré est une édition de l’image originale, similaire au résultat précédent.

Rappel asynchrone

Comme la génération via l’API SeeDream Images Generation prend environ 1 à 2 minutes, si l’API ne répond pas rapidement, la connexion HTTP reste ouverte, ce qui consomme des ressources système supplémentaires. L’API propose donc un support de rappel asynchrone. Le processus est le suivant : lors de la requête client, un champ callback_url est spécifié. Après l’appel API, une réponse immédiate contenant un task_id est renvoyée, représentant l’ID de la tâche. Une fois la tâche terminée, le résultat de génération est envoyé au client via un POST JSON à l’URL callback_url spécifiée, incluant aussi le champ task_id pour associer le résultat à la tâche. Voyons un exemple concret. Après exécution, on obtient immédiatement :

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

Contenu détaillé :

{
    "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.xhuoapi.ai/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg"
        }
    ]
}

On remarque la présence du champ task_id, les autres champs sont similaires à ceux vus précédemment. Ce champ permet d’associer les résultats à la tâche correspondante.

Gestion des erreurs

Lors de l’appel de l’API, en cas d’erreur, l’API renvoie un code d’erreur et un message correspondant. Par exemple :

400 token_mismatched : requête incorrecte, paramètres manquants ou invalides.
400 api_not_implemented : requête incorrecte, paramètres manquants ou invalides.
401 invalid_token : non autorisé, token d’autorisation invalide ou manquant.
429 too_many_requests : trop de requêtes, limite de fréquence dépassée.
500 api_error : erreur interne du 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 appris comment utiliser l’API SeeDream Images Generation pour générer des images à partir de mots-clés. Nous espérons que ce guide vous aidera à mieux intégrer et utiliser cette API. Pour toute question, n’hésitez pas à contacter notre équipe de support technique.

​Processus de demande

​Utilisation de base

​Tâche d’édition d’image

​Rappel asynchrone

​Gestion des erreurs

​Exemple de réponse d’erreur

​Conclusion