Comment utiliser l'API d'images de Seedream 5.0 Pro

Vous pouvez faire fonctionner Seedream 5.0 Pro avec une requête POST, une clé API et une étape de suivi : soumettez la tâche, obtenez un task_id, puis vérifiez le statut jusqu'à ce que l'image soit prête. Si vous manquez cette deuxième étape, vous n'obtiendrez pas le fichier final.

Voici la version courte :

• J'envoie des requêtes à https://api.apimart.ai/v1/images/generations
• J'ajoute Authorization: Bearer YOUR_API_KEY
• Je définis model sur doubao-seedream-5-0-pro
• J'inclus prompt, size et n
• J'utilise le texte vers image pour de nouvelles idées d'images
• J'utilise l'image vers image quand je veux que la sortie reste plus proche d'une ou plusieurs images de référence
• Je stocke les URL des images vite, car elles expirent après 24 heures
• J'utilise des tâches asynchrones pour les sorties lentes comme les images 3K, qui peuvent prendre environ 35 à 50 secondes
• Je surveille le coût, puisque la tarification est d'environ 0,0320 $ par image

La chose principale que je retiendrais : gardez la clé sur le serveur, passez n comme un nombre et utilisez l'interrogation ou un webhook pour les tâches plus longues.

Quelques détails comptent plus qu'ils n'en ont l'air. Par exemple, 401 signifie souvent que la clé est absente ou que le format Bearer est incorrect. 403 signifie souvent que la clé fonctionne, mais que le compte ne peut pas utiliser le modèle ou a un solde faible. Et si j'utilise une sortie Base64, je dois ajouter moi-même le préfixe data:image/...;base64, avant de l'afficher dans un navigateur.

Comparaison rapide

En bref : ce guide montre comment je configurerais l'authentification, construirais le corps de la requête, choisirais entre T2I et I2I, gérerais les tâches asynchrones et sauvegarderais le résultat sans perdre de fichiers ni gaspiller de dépense.

2. Configurer l'accès à l'API et l'authentification

2.1 Créer votre compte APIMart et générer une clé API

Rendez-vous sur le site APIMart et inscrivez-vous pour un nouveau compte ^[8]. Ouvrez ensuite la page de gestion des clés API dans votre tableau de bord et générez une clé API ^[1][5].

Copiez cette clé immédiatement et stockez-la côté serveur. Un gestionnaire de secrets ou une variable d'environnement est l'endroit le plus sûr pour elle.

Ne mettez jamais votre clé API dans le code frontend ni dans un dépôt public. Si quelqu'un obtient cette clé, il peut utiliser votre compte. Dans Node.js, stockez-la avec process.env.API_KEY. Dans un environnement shell, utilisez export API_KEY="your-key-here" ^[1][6].

Avant de construire le flux de requête complet, envoyez une petite requête POST pour vous assurer que l'accès fonctionne ^[1][2]. Si vous obtenez une réponse 200 OK, votre clé et vos permissions sont correctement configurées.

Après cela, vous pouvez passer aux champs de requête, y compris le modèle et le prompt.

2.2 Définir l'URL de base et l'en-tête d'authentification Bearer

Une fois que vous avez choisi le mode T2I ou I2I et que votre clé est prête, vous devez configurer l'authentification avant qu'une requête d'image ne fonctionne. Envoyez ces en-têtes avec chaque requête :

Le préfixe Bearer compte. Omettez-le, et la requête échouera ^[2][5]. Utilisez aussi exactement une espace après Bearer.

Les codes de statut HTTP vous aident à repérer les problèmes d'authentification vite ^[1][10]. Une erreur 401 Unauthorized signifie généralement que la clé est absente, invalide, ou que le préfixe Bearer n'a pas été inclus ^[1][10]. Une erreur 403 Forbidden signifie généralement que la clé elle-même est valide, mais que le compte n'a pas accès au modèle ou n'a pas assez de solde ^[1][10].

Une bonne manière de vérifier cela est de tester d'abord avec cURL. Si cURL fonctionne mais que votre application ne fonctionne pas, le bug se trouve probablement dans le code de requête de votre application ^[2][6].

Une fois l'authentification configurée, l'étape suivante est de construire le corps de la requête d'image.

3. Construire une requête d'image Seedream 5.0 Pro

3.1 Champs requis : modèle, prompt, taille et nombre d'images

Une fois l'authentification configurée, l'étape suivante est de construire le corps JSON.

Un corps de requête valide a besoin de quatre champs : model, prompt, size et n.

Pour Seedream 5.0 Pro, définissez model sur doubao-seedream-5-0-pro ^[1]. Le champ prompt accepte une description en langage naturel et prend en charge jusqu'à 5 000 caractères ^[2]. Le champ size contrôle les dimensions de sortie ou le format d'image. Les valeurs courantes incluent 1024x1024, 2K et des formats d'image comme 1:1 ou 16:9 ^[1][2]. Le champ n définit le nombre d'images à générer, généralement de 1 à 15 ^[1][6].

Un petit détail peut faire trébucher : n doit être un entier, pas une chaîne. Si vous passez "1" au lieu de 1, l'API renvoie une erreur de validation ^[1][5].

3.2 Champs optionnels : images de référence, recherche web et tâches asynchrones

image_urls est le champ principal pour le mode image vers image. Utilisez-le pour envoyer jusqu'à 14 images de référence sous forme d'URL ou d'URI de données Base64. Chaque image doit faire moins de 10 Mo et utiliser un format d'image entre 1:3 et 3:1 ^[1]. Si vous utilisez Base64, incluez le préfixe complet de l'URI de données - data:image/jpeg;base64, - sinon la requête échouera ^[1][5].

web_search peut aider avec les prompts factuels ou en temps réel, comme les événements actuels ou les logos de marque ^[4][7]. Pour la plupart des générations d'images standard, vous n'en aurez pas besoin.

Pour les tâches asynchrones ou par lots, callback_url accepte un point de terminaison HTTPS public où APIMart enverra en POST la charge utile de fin de tâche ^[2].

3.3 Exemples d'appels API en cURL et JavaScript

Voici une requête cURL minimale fonctionnelle pour une seule image 1024×1024 :

curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "doubao-seedream-5-0-pro",
    "prompt": "A sunlit mountain trail in autumn, photorealistic, wide angle",
    "size": "1024x1024",
    "n": 1
  }'

Et voici la même requête en Node.js avec fetch :

const response = await fetch("https://api.apimart.ai/v1/images/generations", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "doubao-seedream-5-0-pro",
    prompt: "A sunlit mountain trail in autumn, photorealistic, wide angle",
    size: "1024x1024",
    n: 1
  })
});

const data = await response.json();
console.log(data);

Gardez cette requête côté serveur. N'exposez jamais votre clé API dans le code côté client.

Une fois la requête soumise, l'étape suivante est d'analyser la charge utile de la réponse.

4. Gérer les réponses et exécuter des flux d'images courants

4.1 Analyser les URL d'images, la sortie Base64 et les objets d'erreur

Une fois la requête terminée, la forme de la réponse reste la même que vous ayez envoyé une image ou plusieurs.

Une réponse réussie renvoie un objet JSON avec quatre champs de premier niveau : model, created (un horodatage Unix), data (un tableau d'objets image) et usage ^[6]. Chaque image générée apparaît dans data sous forme de chaîne url ou b64_json, selon le format que vous avez demandé. Si n est supérieur à 1, data inclut un objet image par sortie.

Si vous avez utilisé le format URL, chaque élément de data stocke le lien de l'image dans .url. Vous pouvez définir cette valeur comme src d'une image dans le navigateur. Un piège : ce sont des liens signés temporaires, et ils expirent après 24 heures ^[6]. Pour les applications de production, téléchargez le fichier immédiatement et sauvegardez-le dans un stockage permanent au lieu de stocker l'URL.

Si vous avez utilisé le format Base64, chaque élément de data stocke la chaîne brute dans .b64_json. Il n'inclut pas le préfixe data:image/...;base64, ^[6]. Pour l'afficher dans un navigateur, ajoutez ce préfixe vous-même :

img.src = "data:image/png;base64", + data.b64_json;

Pour la sauvegarder comme fichier en Python, décodez-la d'abord :

import base64

image_data = base64.b64decode(response["data"][0]["b64_json"])
with open("output.png", "wb") as f:
    f.write(image_data)

Si la requête échoue, la réponse inclut un champ code et un champ message ^[6]. Un 400 signifie généralement une taille non prise en charge ou un paramètre invalide. Un 401 signifie que la requête n'est pas autorisée. Journalisez les deux champs à chaque fois. Dans la plupart des cas, le message pointe directement vers le problème.

Utilisez ces champs pour décider si vous devez stocker, décoder ou afficher la sortie.

---

4.2 Trois types d'images courants que vous pouvez générer avec Seedream 5.0 Pro

Ces trois schémas correspondent aux modes couverts plus tôt : texte seul, référence unique et multi-références.

• Visuels marketing en texte seul. Pour les actifs de campagne qui nécessitent plus de détails, utilisez la résolution 3K (size: "3K") et écrivez un prompt structuré qui commence par le sujet et la composition de la scène, puis ajoute l'éclairage, le style et les détails de couleur. La génération 3K prend 35 à 50 secondes, l'asynchrone est donc généralement le meilleur choix.

• Variations de produit à référence unique. Utilisez le mode image vers image avec une image de référence dans image_urls et un prompt ciblé qui ne change que ce que vous voulez, comme l'arrière-plan, l'éclairage ou la texture de surface. Cela garde la forme et les détails du produit plus proches de l'image source que de générer à partir de zéro. Pour les variations 3K, utilisez callback_url, puisque chaque tâche peut prendre environ 40 secondes ^[2].

• Cohérence multi-références pour la cohérence de marque et de personnage. Si vous avez besoin qu'un personnage ou un élément de marque reste cohérent sur plusieurs images, passez jusqu'à 14 images de référence via image_urls ^[2][3]. Définissez sequential_image_generation sur auto lors de la création de plusieurs sorties à partir d'entrées de référence pour garder la variété sans perdre la cohérence visuelle ^[5][4]. Cela fonctionne bien pour les séries de contenu social, les catalogues de produits et les feuilles de personnage.

Ces schémas ont tendance à mieux fonctionner quand le format de réponse correspond au flux de travail.

---

4.3 Requêtes synchrones vs asynchrones et réponses URL vs Base64

Utilisez cette comparaison pour choisir le format de réponse avant de déployer l'intégration.

Pour les tâches asynchrones, attendez environ 20 secondes avant la première interrogation, puis vérifiez toutes les 3 secondes ^[2]. En production, callback_url est la meilleure option car elle évite les boucles d'interrogation et réduit la charge serveur ^[2][9].

Utilisez les réponses URL par défaut. Passez à Base64 seulement quand vous avez besoin des données d'image dans la même réponse.

5. Liste de vérification finale pour une intégration fiable de Seedream 5.0 Pro

Après votre premier appel de test réussi, parcourez cette liste de vérification avant de passer à l'échelle de production. C'est une manière simple d'attraper les problèmes qui ont tendance à bloquer net les lancements.

Authentification et sécurité des clés. Gardez votre clé API dans une variable d'environnement ou un gestionnaire de secrets. Envoyez les requêtes depuis votre backend avec Authorization: Bearer <your_key>.

Validez vos paramètres de requête avant de les envoyer. Vérifiez la chaîne du modèle, passez n comme un entier, gardez image_urls dans la limite autorisée et assurez-vous que la size demandée est prise en charge.

Pour les tâches qui prennent plus de temps qu'un aperçu rapide, ajustez votre chemin de livraison en conséquence. Définissez des délais d'attente en fonction de la taille de sortie, et utilisez callback_url pour les tâches longues au lieu de l'interrogation.

Une fois l'image prête, traitez la livraison comme un problème de stockage, pas seulement un problème de réponse. Si vous utilisez la sortie URL, téléchargez le fichier immédiatement et déplacez-le vers un stockage permanent. Les URL signées expirent après 24 heures ^[6].

Testez les prompts sur un petit lot avant de passer à l'échelle. Seedream 5.0 est facturé à environ 0,0320 $ par image générée ^[2]. Journalisez createTime, completeTime et costTime pour pouvoir surveiller la latence et la dépense ^[2].

FAQ

Comment vérifier une tâche d'image asynchrone après avoir obtenu un task_id ?

Utilisez le task_id renvoyé pour vérifier le statut de votre tâche d'image asynchrone.

Envoyez une requête GET au point de terminaison de statut que l'API vous donne. Dans beaucoup d'API, cela ressemble à :

• /v1/tasks/{task_id}
• ou un point de terminaison de style requête avec le task_id

Pour un usage en production, attendez environ 20 secondes après avoir créé la tâche avant votre première vérification de statut. Ensuite, interrogez toutes les 3 secondes jusqu'à ce que le statut de la tâche affiche completed.

Une fois la tâche terminée, lisez la charge utile de la réponse et extrayez-en les URL des images.

Quand devrais-je utiliser la sortie URL au lieu de Base64 ?

Utilisez la sortie URL dans la plupart des cas. Elle vous donne un lien direct vers l'image générée, ce qui facilite son intégration dans les applications web ou mobiles.

Utilisez Base64 seulement quand votre configuration a besoin des données d'image en ligne dans le corps de la réponse, comme le traitement en mémoire ou quand vous voulez éviter une seconde requête. Pour les actifs 4K haute résolution, la sortie URL est généralement plus efficace.

Quelle est la meilleure manière d'éviter de perdre les images générées ?

Sauvegardez rapidement les images générées, car les liens d'images de l'API ne sont valides que 72 heures.

L'API Seedream 5.0 Pro fonctionne de manière asynchrone. Cela signifie que vous n'obtiendrez pas l'URL de l'image immédiatement. D'abord, vous obtenez un identifiant de tâche. Ensuite, vous utilisez cet identifiant de tâche pour récupérer l'URL de l'image.

Pour éviter de perdre la sortie, vous avez deux options principales :

• Interroger avec l'identifiant de tâche jusqu'à ce que l'image soit prête
• Utiliser une URL de rappel pour que votre système puisse recevoir, capturer et stocker l'image avant que le lien n'expire

Si vous attendez trop longtemps, l'URL expirera et l'image pourra être perdue.